<?xml version="1.0" encoding="utf-8"?>
-<database title="Open vSwitch Configuration Database">
+<database name="ovs-vswitchd.conf.db" title="Open vSwitch Configuration Database">
<p>
A database with this schema holds the configuration for one Open
vSwitch daemon. The top-level configuration for the daemon is the
table="Open_vSwitch"/> table. Records that are not reachable from
the <ref table="Open_vSwitch"/> table are automatically deleted
from the database, except for records in a few distinguished
- ``root set'' tables noted below.
+ ``root set'' tables.
</p>
+ <h2>Common Columns</h2>
+
+ <p>
+ Most tables contain two special columns, named <code>other_config</code>
+ and <code>external_ids</code>. These columns have the same form and
+ purpose each place that they appear, so we describe them here to save space
+ later.
+ </p>
+
+ <dl>
+ <dt><code>other_config</code>: map of string-string pairs</dt>
+ <dd>
+ <p>
+ Key-value pairs for configuring rarely used features. Supported keys,
+ along with the forms taken by their values, are documented individually
+ for each table.
+ </p>
+ <p>
+ A few tables do not have <code>other_config</code> columns because no
+ key-value pairs have yet been defined for them.
+ </p>
+ </dd>
+
+ <dt><code>external_ids</code>: map of string-string pairs</dt>
+ <dd>
+ 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. In some cases, where key-value pairs have been defined that are
+ likely to be widely useful, they are documented individually for each
+ table.
+ </dd>
+ </dl>
+
<table name="Open_vSwitch" title="Open vSwitch configuration.">
Configuration for an Open vSwitch daemon. There must be exactly
one record in the <ref table="Open_vSwitch"/> table.
SSL used globally by the daemon.
</column>
- <column name="other_config">
- Key-value pairs for configuring rarely used Open vSwitch features. The
- currently defined key-value pairs are:
- <dl>
- <dt><code>enable-statistics</code></dt>
- <dd>
- Set to <code>true</code> to enable populating the <ref
- column="statistics"/> column or <code>false</code> (the default)
- disable populating it.
- </dd>
- </dl>
+ <column name="external_ids" key="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
+ <ref column="external_ids" key="xs-system-uuid"/>.
</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. The currently
- defined common key-value pairs are:
- <dl>
- <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
- <ref column="external_ids" key="xs-system-uuid"/>.</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 name="external_ids" key="xs-system-uuid">
+ The Citrix XenServer universally unique identifier for the physical
+ host as displayed by <code>xe host-list</code>.
+ </column>
+
+ <column name="other_config" key="stats-update-interval"
+ type='{"type": "integer", "minInteger": 5000}'>
+ <p>
+ Interval for updating statistics to the database, in milliseconds.
+ This option will affect the update of the <code>statistics</code>
+ column in the following tables: <code>Port</code>, <code>Interface
+ </code>, <code>Mirror</code>.
+ </p>
+ <p>
+ Default value is 5000 ms.
+ </p>
+ <p>
+ Getting statistics more frequently can be achieved via OpenFlow.
+ </p>
+ </column>
+
+ <column name="other_config" key="flow-restore-wait"
+ type='{"type": "boolean"}'>
+ <p>
+ When <code>ovs-vswitchd</code> starts up, it has an empty flow table
+ and therefore it handles all arriving packets in its default fashion
+ according to its configuration, by dropping them or sending them to
+ an OpenFlow controller or switching them as a standalone switch.
+ This behavior is ordinarily desirable. However, if
+ <code>ovs-vswitchd</code> is restarting as part of a ``hot-upgrade,''
+ then this leads to a relatively long period during which packets are
+ mishandled.
+ </p>
+ <p>
+ This option allows for improvement. When <code>ovs-vswitchd</code>
+ starts with this value set as <code>true</code>, it will neither
+ flush or expire previously set datapath flows nor will it send and
+ receive any packets to or from the datapath. When this value is
+ later set to <code>false</code>, <code>ovs-vswitchd</code> will
+ start receiving packets from the datapath and re-setup the flows.
+ </p>
+ <p>
+ Thus, with this option, the procedure for a hot-upgrade of
+ <code>ovs-vswitchd</code> becomes roughly the following:
+ </p>
+ <ol>
+ <li>
+ Stop <code>ovs-vswitchd</code>.
+ </li>
+ <li>
+ Set <ref column="other_config" key="flow-restore-wait"/>
+ to <code>true</code>.
+ </li>
+ <li>
+ Start <code>ovs-vswitchd</code>.
+ </li>
+ <li>
+ Use <code>ovs-ofctl</code> (or some other program, such as an
+ OpenFlow controller) to restore the OpenFlow flow table
+ to the desired state.
+ </li>
+ <li>
+ Set <ref column="other_config" key="flow-restore-wait"/>
+ to <code>false</code> (or remove it entirely from the database).
+ </li>
+ </ol>
+ <p>
+ The <code>ovs-ctl</code>'s ``restart'' and ``force-reload-kmod''
+ functions use the above config option during hot upgrades.
+ </p>
+ </column>
+
+ <column name="other_config" key="flow-limit"
+ type='{"type": "integer", "minInteger": 0}'>
+ <p>
+ The maximum
+ number of flows allowed in the datapath flow table. Internally OVS
+ will choose a flow limit which will likely be lower than this number,
+ based on real time network conditions. Tweaking this value is
+ discouraged unless you know exactly what you're doing.
+ </p>
+ <p>
+ The default is 200000.
+ </p>
+ </column>
+
+ <column name="other_config" key="max-idle"
+ type='{"type": "integer", "minInteger": 500}'>
+ <p>
+ The maximum time (in ms) that idle flows will remain cached in the
+ datapath. Internally OVS will check the validity and activity for
+ datapath flows regularly and may expire flows quicker than this
+ number, based on real time network conditions. Tweaking this
+ value is discouraged unless you know exactly what you're doing.
+ </p>
+ <p>
+ The default is 10000.
+ </p>
+ </column>
+
+ <column name="other_config" key="pmd-cpu-mask">
+ <p>
+ Specifies CPU mask for setting the cpu affinity of PMD (Poll
+ Mode Driver) threads. Value should be in the form of hex string,
+ similar to the dpdk EAL '-c COREMASK' option input or the 'taskset'
+ mask input.
+ </p>
+ <p>
+ The lowest order bit corresponds to the first CPU core. A set bit
+ means the corresponding core is available and a pmd thread will be
+ created and pinned to it. If the input does not cover all cores,
+ those uncovered cores are considered not set.
+ </p>
+ <p>
+ If not specified, one pmd thread will be created for each numa node
+ and pinned to any available core on the numa node by default.
+ </p>
+ </column>
+
+ <column name="other_config" key="n-handler-threads"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ Specifies the number of threads for software datapaths to use for
+ handling new flows. The default the number of online CPU cores minus
+ the number of revalidators.
+ </p>
+ <p>
+ This configuration is per datapath. If you have more than one
+ software datapath (e.g. some <code>system</code> bridges and some
+ <code>netdev</code> bridges), then the total number of threads is
+ <code>n-handler-threads</code> times the number of software
+ datapaths.
+ </p>
+ </column>
+
+ <column name="other_config" key="n-revalidator-threads"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ Specifies the number of threads for software datapaths to use for
+ revalidating flows in the datapath. Typically, there is a direct
+ correlation between the number of revalidator threads, and the number
+ of flows allowed in the datapath. The default is the number of cpu
+ cores divided by four plus one. If <code>n-handler-threads</code> is
+ set, the default changes to the number of cpu cores minus the number
+ of handler threads.
+ </p>
+ <p>
+ This configuration is per datapath. If you have more than one
+ software datapath (e.g. some <code>system</code> bridges and some
+ <code>netdev</code> bridges), then the total number of threads is
+ <code>n-handler-threads</code> times the number of software
+ datapaths.
+ </p>
</column>
</group>
configuration changes.
</column>
- <column name="capabilities">
- Describes functionality supported by the hardware and software platform
- on which this Open vSwitch is based. Clients should not modify this
- column. See the <ref table="Capability"/> description for defined
- capability categories and the meaning of associated
- <ref table="Capability"/> records.
- </column>
-
- <column name="statistics">
+ <group title="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.
+ The <code>statistics</code> column contains 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>
- <p>
- Statistics are disabled unless <ref column="other-config"
- key="enable-statistics"/> is set to <code>true</code>.
- </p>
+ <column name="other_config" key="enable-statistics"
+ type='{"type": "boolean"}'>
+ Statistics are disabled by default to avoid overhead in the common
+ case when statistics gathering is not useful. Set this value to
+ <code>true</code> to enable populating the <ref column="statistics"/>
+ column or to <code>false</code> to explicitly disable it.
+ </column>
- <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>
+ <column name="statistics" key="cpu"
+ type='{"type": "integer", "minInteger": 1}'>
+ <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>
+ </column>
- <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>
+ <column name="statistics" key="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.
+ </column>
- <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>
+ <column name="statistics" key="memory">
+ <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>
- <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>
+ <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>
- 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>
+ <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>
+ </column>
- <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>
+ <column name="statistics" key="process_NAME">
+ <p>
+ One such key-value pair, with <code>NAME</code> replaced by
+ a process name, 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>
- <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>
+ <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>
- 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>
+ 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>
- 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>
+ 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>
- 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>
+ <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>
+ </column>
- <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>
+ <column name="statistics" key="file_systems">
+ <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>
- <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>
+ <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>
+ <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>
+ </column>
+ </group>
</group>
<group title="Version Reporting">
<column name="ovs_version">
The Open vSwitch version number, e.g. <code>1.1.0</code>.
- If Open vSwitch was configured with a build number, then it is
- also included, e.g. <code>1.1.0+build6579</code>.
</column>
<column name="db_version">
</group>
+ <group title="Capabilities">
+ <p>
+ These columns report capabilities of the Open vSwitch instance.
+ </p>
+ <column name="datapath_types">
+ <p>
+ This column reports the different dpifs registered with the system.
+ These are the values that this instance supports in the <ref
+ column="datapath_type" table="Bridge"/> column of the <ref
+ table="Bridge"/> table.
+ </p>
+ </column>
+ <column name="iface_types">
+ <p>
+ This column reports the different netdevs registered with the system.
+ These are the values that this instance supports in the <ref
+ column="type" table="Interface"/> column of the <ref
+ table="Interface"/> table.
+ </p>
+ </column>
+ </group>
+
<group title="Database Configuration">
<p>
These columns primarily configure the Open vSwitch database
for more information.
</column>
</group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
</table>
<table name="Bridge">
<group title="Core Features">
<column name="name">
- Bridge identifier. Should be alphanumeric and no more than about 8
- bytes long. Must be unique among the names of ports, interfaces, and
- bridges on a host.
+ <p>
+ Bridge identifier. Should be alphanumeric and no more than about 8
+ bytes long. Must be unique among the names of ports, interfaces, and
+ bridges on a host.
+ </p>
+
+ <p>
+ Forward and backward slashes are prohibited in bridge names.
+ </p>
</column>
<column name="ports">
</column>
<column name="sflow">
- sFlow configuration.
+ sFlow(R) configuration.
+ </column>
+
+ <column name="ipfix">
+ IPFIX configuration.
</column>
<column name="flood_vlans">
a different type of mirror instead.
</p>
</column>
+
+ <column name="auto_attach">
+ Auto Attach configuration.
+ </column>
</group>
<group title="OpenFlow Configuration">
<column name="controller">
- OpenFlow controller set. If unset, then no OpenFlow controllers
- will be used.
+ <p>
+ OpenFlow controller set. If unset, then no OpenFlow controllers
+ will be used.
+ </p>
+
+ <p>
+ If there are primary controllers, removing all of them clears the
+ flow table. If there are no primary controllers, adding one also
+ clears the flow table. Other changes to the set of controllers, such
+ as adding or removing a service controller, adding another primary
+ controller to supplement an existing primary controller, or removing
+ only one of two primary controllers, have no effect on the flow
+ table.
+ </p>
+ </column>
+
+ <column name="flow_tables">
+ Configuration for OpenFlow tables. Each pair maps from an OpenFlow
+ table ID to configuration for that table.
</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>
+ 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>
+ The default is <code>standalone</code> if the value is unset, but
+ future versions of Open vSwitch may change the default.
+ </p>
+ <p>
+ The <code>standalone</code> mode can create forwarding loops on a
+ bridge that has more than one uplink port unless STP is enabled. To
+ avoid loops on such a bridge, configure <code>secure</code> mode or
+ enable STP (see <ref column="stp_enable"/>).
+ </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>
+ <ref column="fail_mode"/> is considered only when none of the
+ configured controllers can be contacted.</p>
+ <p>
+ Changing <ref column="fail_mode"/> when no primary controllers are
+ configured clears the flow table.
+ </p>
</column>
<column name="datapath_id">
(Setting this column has no useful effect. Set <ref
column="other-config" key="datapath-id"/> instead.)
</column>
- </group>
-
- <group title="Other Features">
- <column name="datapath_type">
- Name of datapath provider. The kernel datapath has
- type <code>system</code>. The userspace datapath has
- type <code>netdev</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. The currently
- defined key-value pairs are:
- <dl>
- <dt><code>bridge-id</code></dt>
- <dd>A unique identifier of the bridge. On Citrix XenServer this will
- commonly be the same as
- <ref column="external_ids" key="xs-network-uuids"/>.</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 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>
- <column name="other_config">
- Key-value pairs for configuring rarely used bridge
- features. The currently defined key-value pairs are:
- <dl>
- <dt><code>datapath-id</code></dt>
- <dd>Exactly 16 hex
- digits to set the OpenFlow datapath ID to a specific
- 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>
- <dt><code>flow-eviction-threshold</code></dt>
- <dd>
- A number of flows as a nonnegative integer. This sets number
- of flows at which eviction from the kernel flow table will
- be triggered.
- If there are a large number of flows then increasing this
- value to around the number of flows present
- can result in reduced CPU usage and packet loss.
- </dd>
- <dd>
- The default is 1000.
- </dd>
- <dd>
- Values below 100 will be rounded up to 100.
- </dd>
- <dt><code>forward-bpdu</code></dt>
- <dd>
- Option to allow forwarding of BPDU frames when NORMAL
- action if invoked. Frames with reserved Ethernet addresses
- (e.g. STP BPDU) will be forwarded when this option is enabled.
- If the Open vSwitch bridge is used to connect different
- Ethernet networks, and if Open vSwitch node does not run STP,
- then this option should be enabled.
- Default is disabled, set to <code>true</code> to enable.
- </dd>
- </dl>
- </column>
- </group>
- </table>
+ <column name="datapath_version">
+ <p>
+ Reports the version number of the Open vSwitch datapath in use.
+ This allows management software to detect and report discrepancies
+ between Open vSwitch userspace and datapath versions. (The <ref
+ column="ovs_version" table="Open_vSwitch"/> column in the <ref
+ table="Open_vSwitch"/> reports the Open vSwitch userspace version.)
+ The version reported depends on the datapath in use:
+ </p>
- <table name="Port" table="Port or bond configuration.">
- <p>A port within a <ref table="Bridge"/>.</p>
- <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
- <ref column="interfaces"/> column. Such a port logically
- corresponds to a port on a physical Ethernet switch. A port
- with more than one interface is a ``bonded port'' (see
- <ref group="Bonding Configuration"/>).</p>
- <p>Some properties that one might think as belonging to a port are actually
- part of the port's <ref table="Interface"/> members.</p>
+ <ul>
+ <li>
+ When the kernel module included in the Open vSwitch source tree is
+ used, this column reports the Open vSwitch version from which the
+ module was taken.
+ </li>
- <column name="name">
- Port name. Should be alphanumeric and no more than about 8
- bytes long. May be the same as the interface name, for
- non-bonded ports. Must otherwise be unique among the names of
- ports, interfaces, and bridges on a host.
- </column>
+ <li>
+ When the kernel module that is part of the upstream Linux kernel is
+ used, this column reports <code><unknown></code>.
+ </li>
- <column name="interfaces">
- The port's interfaces. If there is more than one, this is a
- bonded Port.
- </column>
+ <li>
+ When the datapath is built into the <code>ovs-vswitchd</code>
+ binary, this column reports <code><built-in></code>. A
+ built-in datapath is by definition the same version as the rest of
+ the Open VSwitch userspace.
+ </li>
- <group title="VLAN Configuration">
- <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"/>. 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"/>. Its
- <ref column="trunks"/> value must be empty.</li>
+ <li>
+ Other datapaths (such as the Hyper-V kernel datapath) currently
+ report <code><unknown></code>.
+ </li>
</ul>
- If <ref column="trunks"/> and <ref column="tag"/> are both
- nonempty, the configuration is ill-formed.
- </p>
- <column name="tag">
- <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.
+ A version discrepancy between <code>ovs-vswitchd</code> and the
+ datapath in use is not normally cause for alarm. The Open vSwitch
+ kernel datapaths for Linux and Hyper-V, in particular, are designed
+ for maximum inter-version compatibility: any userspace version works
+ with with any kernel version. Some reasons do exist to insist on
+ particular user/kernel pairings. First, newer kernel versions add
+ new features, that can only be used by new-enough userspace, e.g.
+ VXLAN tunneling requires certain minimal userspace and kernel
+ versions. Second, as an extension to the first reason, some newer
+ kernel versions add new features for enhancing performance that only
+ new-enough userspace versions can take advantage of.
</p>
+ </column>
+
+ <column name="other_config" key="datapath-id">
+ Exactly 16 hex digits to set the OpenFlow datapath ID to a specific
+ value. May not be all-zero.
+ </column>
+
+ <column name="other_config" key="dp-desc">
+ Human readable description of datapath. It it a maximum 256
+ byte-long free-form string to describe the datapath for
+ debugging purposes, e.g. <code>switch3 in room 3120</code>.
+ </column>
+
+ <column name="other_config" key="disable-in-band"
+ type='{"type": "boolean"}'>
+ If set to <code>true</code>, disable in-band control on the bridge
+ regardless of controller and manager settings.
+ </column>
+
+ <column name="other_config" key="in-band-queue"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
+ 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.
+ </column>
+
+ <column name="protocols">
<p>
- When a frame with a 802.1Q header that indicates a nonzero
- VLAN is received on an access port, it is discarded.
+ List of OpenFlow protocols that may be used when negotiating
+ a connection with a controller. OpenFlow 1.0, 1.1, 1.2, and
+ 1.3 are enabled by default if this column is empty.
</p>
- </column>
- <column name="trunks">
<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.
+ OpenFlow 1.4 is not enabled by default because its implementation is
+ missing features.
</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.
+ OpenFlow 1.5 has the same risks as OpenFlow 1.4, but it is even more
+ experimental because the OpenFlow 1.5 specification is still under
+ development and thus subject to change. Pass
+ <code>--enable-of15</code> to <code>ovs-vswitchd</code> to allow
+ OpenFlow 1.5 to be enabled.
</p>
</column>
</group>
- <group title="Bonding Configuration">
- <p>A port that has more than one interface is a ``bonded port.'' Bonding
- allows for load balancing and fail-over. Some kinds of bonding will
- work with any kind of upstream switch:</p>
+ <group title="Spanning Tree Configuration">
+ <p>
+ The IEEE 802.1D Spanning Tree Protocol (STP) is a network protocol
+ that ensures loop-free topologies. It allows redundant links to
+ be included in the network to provide automatic backup paths if
+ the active links fails.
+ </p>
- <dl>
- <dt><code>balance-slb</code></dt>
- <dd>
- Balances flows among slaves based on source MAC address and output
- VLAN, with periodic rebalancing as traffic patterns change.
- </dd>
+ <p>
+ These settings configure the slower-to-converge but still widely
+ supported version of Spanning Tree Protocol, sometimes known as
+ 802.1D-1998. Open vSwitch also supports the newer Rapid Spanning Tree
+ Protocol (RSTP), documented later in the section titled <code>Rapid
+ Spanning Tree Configuration</code>.
+ </p>
+
+ <group title="STP Configuration">
+ <column name="stp_enable" type='{"type": "boolean"}'>
+ <p>
+ Enable spanning tree on the bridge. By default, STP is disabled
+ on bridges. Bond, internal, and mirror ports are not supported
+ and will not participate in the spanning tree.
+ </p>
+
+ <p>
+ STP and RSTP are mutually exclusive. If both are enabled, RSTP
+ will be used.
+ </p>
+ </column>
+
+ <column name="other_config" key="stp-system-id">
+ The bridge's STP identifier (the lower 48 bits of the bridge-id)
+ in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ By default, the identifier is the MAC address of the bridge.
+ </column>
+
+ <column name="other_config" key="stp-priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
+ The bridge's relative priority value for determining the root
+ bridge (the upper 16 bits of the bridge-id). A bridge with the
+ lowest bridge-id is elected the root. By default, the priority
+ is 0x8000.
+ </column>
+
+ <column name="other_config" key="stp-hello-time"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
+ The interval between transmissions of hello messages by
+ designated ports, in seconds. By default the hello interval is
+ 2 seconds.
+ </column>
+
+ <column name="other_config" key="stp-max-age"
+ type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
+ The maximum age of the information transmitted by the bridge
+ when it is the root bridge, in seconds. By default, the maximum
+ age is 20 seconds.
+ </column>
+
+ <column name="other_config" key="stp-forward-delay"
+ type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
+ The delay to wait between transitioning root and designated
+ ports to <code>forwarding</code>, in seconds. By default, the
+ forwarding delay is 15 seconds.
+ </column>
+
+ <column name="other_config" key="mcast-snooping-aging-time"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ The maximum number of seconds to retain a multicast snooping entry for
+ which no packets have been seen. The default is currently 300
+ seconds (5 minutes). The value, if specified, is forced into a
+ reasonable range, currently 15 to 3600 seconds.
+ </p>
+ </column>
+
+ <column name="other_config" key="mcast-snooping-table-size"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ The maximum number of multicast snooping addresses to learn. The
+ default is currently 2048. The value, if specified, is forced into
+ a reasonable range, currently 10 to 1,000,000.
+ </p>
+ </column>
+ <column name="other_config" key="mcast-snooping-disable-flood-unregistered"
+ type='{"type": "boolean"}'>
+ <p>
+ If set to <code>false</code>, unregistered multicast packets are forwarded
+ to all ports.
+ If set to <code>true</code>, unregistered multicast packets are forwarded
+ to ports connected to multicast routers.
+ </p>
+ </column>
+ </group>
+
+ <group title="STP Status">
+ <p>
+ These key-value pairs report the status of 802.1D-1998. They are
+ present only if STP is enabled (via the <ref column="stp_enable"/>
+ column).
+ </p>
+ <column name="status" key="stp_bridge_id">
+ The bridge ID used in spanning tree advertisements, in the form
+ <var>xxxx</var>.<var>yyyyyyyyyyyy</var> where the <var>x</var>s are
+ the STP priority, the <var>y</var>s are the STP system ID, and each
+ <var>x</var> and <var>y</var> is a hex digit.
+ </column>
+ <column name="status" key="stp_designated_root">
+ The designated root for this spanning tree, in the same form as <ref
+ column="status" key="stp_bridge_id"/>. If this bridge is the root,
+ this will have the same value as <ref column="status"
+ key="stp_bridge_id"/>, otherwise it will differ.
+ </column>
+ <column name="status" key="stp_root_path_cost">
+ The path cost of reaching the designated bridge. A lower number is
+ better. The value is 0 if this bridge is the root, otherwise it is
+ higher.
+ </column>
+ </group>
+ </group>
+
+ <group title="Rapid Spanning Tree">
+ <p>
+ Rapid Spanning Tree Protocol (RSTP), like STP, is a network protocol
+ that ensures loop-free topologies. RSTP superseded STP with the
+ publication of 802.1D-2004. Compared to STP, RSTP converges more
+ quickly and recovers more quickly from failures.
+ </p>
+
+ <group title="RSTP Configuration">
+ <column name="rstp_enable" type='{"type": "boolean"}'>
+ <p>
+ Enable Rapid Spanning Tree on the bridge. By default, RSTP is disabled
+ on bridges. Bond, internal, and mirror ports are not supported
+ and will not participate in the spanning tree.
+ </p>
+
+ <p>
+ STP and RSTP are mutually exclusive. If both are enabled, RSTP
+ will be used.
+ </p>
+ </column>
+
+ <column name="other_config" key="rstp-address">
+ The bridge's RSTP address (the lower 48 bits of the bridge-id)
+ in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ By default, the address is the MAC address of the bridge.
+ </column>
+
+ <column name="other_config" key="rstp-priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 61440}'>
+ The bridge's relative priority value for determining the root
+ bridge (the upper 16 bits of the bridge-id). A bridge with the
+ lowest bridge-id is elected the root. By default, the priority
+ is 0x8000 (32768). This value needs to be a multiple of 4096,
+ otherwise it's rounded to the nearest inferior one.
+ </column>
+
+ <column name="other_config" key="rstp-ageing-time"
+ type='{"type": "integer", "minInteger": 10, "maxInteger": 1000000}'>
+ The Ageing Time parameter for the Bridge. The default value
+ is 300 seconds.
+ </column>
+
+ <column name="other_config" key="rstp-force-protocol-version"
+ type='{"type": "integer"}'>
+ The Force Protocol Version parameter for the Bridge. This
+ can take the value 0 (STP Compatibility mode) or 2
+ (the default, normal operation).
+ </column>
+
+ <column name="other_config" key="rstp-max-age"
+ type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
+ The maximum age of the information transmitted by the Bridge
+ when it is the Root Bridge. The default value is 20.
+ </column>
+
+ <column name="other_config" key="rstp-forward-delay"
+ type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
+ The delay used by STP Bridges to transition Root and Designated
+ Ports to Forwarding. The default value is 15.
+ </column>
+
+ <column name="other_config" key="rstp-transmit-hold-count"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
+ The Transmit Hold Count used by the Port Transmit state machine
+ to limit transmission rate. The default value is 6.
+ </column>
+ </group>
+
+ <group title="RSTP Status">
+ <p>
+ These key-value pairs report the status of 802.1D-2004. They are
+ present only if RSTP is enabled (via the <ref column="rstp_enable"/>
+ column).
+ </p>
+ <column name="rstp_status" key="rstp_bridge_id">
+ The bridge ID used in rapid spanning tree advertisements, in the form
+ <var>x</var>.<var>yyy</var>.<var>zzzzzzzzzzzz</var> where
+ <var>x</var> is the RSTP priority, the <var>y</var>s are a locally
+ assigned system ID extension, the <var>z</var>s are the STP system
+ ID, and each <var>x</var>, <var>y</var>, or <var>z</var> is a hex
+ digit.
+ </column>
+ <column name="rstp_status" key="rstp_root_id">
+ The root of this spanning tree, in the same form as <ref
+ column="rstp_status" key="rstp_bridge_id"/>. If this bridge is the
+ root, this will have the same value as <ref column="rstp_status"
+ key="rstp_bridge_id"/>, otherwise it will differ.
+ </column>
+ <column name="rstp_status" key="rstp_root_path_cost"
+ type='{"type": "integer", "minInteger": 0}'>
+ The path cost of reaching the root. A lower number is better. The
+ value is 0 if this bridge is the root, otherwise it is higher.
+ </column>
+ <column name="rstp_status" key="rstp_designated_id">
+ The RSTP designated ID, in the same form as <ref column="rstp_status"
+ key="rstp_bridge_id"/>.
+ </column>
+ <column name="rstp_status" key="rstp_designated_port_id">
+ The RSTP designated port ID, as a 4-digit hex number.
+ </column>
+ <column name="rstp_status" key="rstp_bridge_port_id">
+ The RSTP bridge port ID, as a 4-digit hex number.
+ </column>
+ </group>
+ </group>
+
+ <group title="Multicast Snooping Configuration">
+ Multicast snooping (RFC 4541) monitors the Internet Group Management
+ Protocol (IGMP) and Multicast Listener Discovery traffic between hosts
+ and multicast routers. The switch uses what IGMP and MLD snooping
+ learns to forward multicast traffic only to interfaces that are connected
+ to interested receivers. Currently it supports IGMPv1, IGMPv2, IGMPv3,
+ MLDv1 and MLDv2 protocols.
+
+ <column name="mcast_snooping_enable">
+ Enable multicast snooping on the bridge. For now, the default
+ is disabled.
+ </column>
+ </group>
+
+ <group title="Other Features">
+ <column name="datapath_type">
+ Name of datapath provider. The kernel datapath has type
+ <code>system</code>. The userspace datapath has type
+ <code>netdev</code>. A manager may refer to the <ref
+ table="Open_vSwitch" column="datapath_types"/> column of the <ref
+ table="Open_vSwitch"/> table for a list of the types accepted by this
+ Open vSwitch instance.
+ </column>
+
+ <column name="external_ids" key="bridge-id">
+ A unique identifier of the bridge. On Citrix XenServer this will
+ commonly be the same as
+ <ref column="external_ids" key="xs-network-uuids"/>.
+ </column>
+
+ <column name="external_ids" key="xs-network-uuids">
+ Semicolon-delimited set of universally unique identifier(s) for 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>.
+ </column>
+
+ <column name="other_config" key="hwaddr">
+ 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.
+ </column>
+
+ <column name="other_config" key="forward-bpdu"
+ type='{"type": "boolean"}'>
+
+ <p>
+ Controls forwarding of BPDUs and other network control frames when
+ NORMAL action is invoked. When this option is <code>false</code> or
+ unset, frames with reserved Ethernet addresses (see table below) will
+ not be forwarded. When this option is <code>true</code>, such frames
+ will not be treated specially.
+ </p>
+
+ <p>
+ The above general rule has the following exceptions:
+ </p>
+
+ <ul>
+ <li>
+ If STP is enabled on the bridge (see the <ref column="stp_enable"
+ table="Bridge"/> column in the <ref table="Bridge"/> table), the
+ bridge processes all received STP packets and never passes them to
+ OpenFlow or forwards them. This is true even if STP is disabled on
+ an individual port.
+ </li>
+
+ <li>
+ If LLDP is enabled on an interface (see the <ref column="lldp"
+ table="Interface"/> column in the <ref table="Interface"/> table),
+ the interface processes received LLDP packets and never passes them
+ to OpenFlow or forwards them.
+ </li>
+ </ul>
+
+ <p>
+ Set this option to <code>true</code> if the Open vSwitch bridge
+ connects different Ethernet networks and is not configured to
+ participate in STP.
+ </p>
+
+ <p>
+ This option affects packets with the following destination MAC
+ addresses:
+ </p>
+
+ <dl>
+ <dt><code>01:80:c2:00:00:00</code></dt>
+ <dd>IEEE 802.1D Spanning Tree Protocol (STP).</dd>
+
+ <dt><code>01:80:c2:00:00:01</code></dt>
+ <dd>IEEE Pause frame.</dd>
+
+ <dt><code>01:80:c2:00:00:0<var>x</var></code></dt>
+ <dd>Other reserved protocols.</dd>
+
+ <dt><code>00:e0:2b:00:00:00</code></dt>
+ <dd>Extreme Discovery Protocol (EDP).</dd>
+
+ <dt>
+ <code>00:e0:2b:00:00:04</code> and <code>00:e0:2b:00:00:06</code>
+ </dt>
+ <dd>Ethernet Automatic Protection Switching (EAPS).</dd>
+
+ <dt><code>01:00:0c:cc:cc:cc</code></dt>
+ <dd>
+ Cisco Discovery Protocol (CDP), VLAN Trunking Protocol (VTP),
+ Dynamic Trunking Protocol (DTP), Port Aggregation Protocol (PAgP),
+ and others.
+ </dd>
+
+ <dt><code>01:00:0c:cc:cc:cd</code></dt>
+ <dd>Cisco Shared Spanning Tree Protocol PVSTP+.</dd>
+
+ <dt><code>01:00:0c:cd:cd:cd</code></dt>
+ <dd>Cisco STP Uplink Fast.</dd>
+
+ <dt><code>01:00:0c:00:00:00</code></dt>
+ <dd>Cisco Inter Switch Link.</dd>
+
+ <dt><code>01:00:0c:cc:cc:c<var>x</var></code></dt>
+ <dd>Cisco CFM.</dd>
+ </dl>
+ </column>
+
+ <column name="other_config" key="mac-aging-time"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ The maximum number of seconds to retain a MAC learning entry for
+ which no packets have been seen. The default is currently 300
+ seconds (5 minutes). The value, if specified, is forced into a
+ reasonable range, currently 15 to 3600 seconds.
+ </p>
+
+ <p>
+ A short MAC aging time allows a network to more quickly detect that a
+ host is no longer connected to a switch port. However, it also makes
+ it more likely that packets will be flooded unnecessarily, when they
+ are addressed to a connected host that rarely transmits packets. To
+ reduce the incidence of unnecessary flooding, use a MAC aging time
+ longer than the maximum interval at which a host will ordinarily
+ transmit packets.
+ </p>
+ </column>
+
+ <column name="other_config" key="mac-table-size"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ The maximum number of MAC addresses to learn. The default is
+ currently 2048. The value, if specified, is forced into a reasonable
+ range, currently 10 to 1,000,000.
+ </p>
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Port" table="Port or bond configuration.">
+ <p>A port within a <ref table="Bridge"/>.</p>
+ <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
+ <ref column="interfaces"/> column. Such a port logically
+ corresponds to a port on a physical Ethernet switch. A port
+ with more than one interface is a ``bonded port'' (see
+ <ref group="Bonding Configuration"/>).</p>
+ <p>Some properties that one might think as belonging to a port are actually
+ part of the port's <ref table="Interface"/> members.</p>
+
+ <column name="name">
+ Port name. Should be alphanumeric and no more than about 8
+ bytes long. May be the same as the interface name, for
+ non-bonded ports. Must otherwise be unique among the names of
+ ports, interfaces, and bridges on a host.
+ </column>
+
+ <column name="interfaces">
+ The port's interfaces. If there is more than one, this is a
+ bonded Port.
+ </column>
+
+ <group title="VLAN Configuration">
+ <p>Bridge ports support the following types of VLAN configuration:</p>
+ <dl>
+ <dt>trunk</dt>
+ <dd>
+ <p>
+ A trunk port carries packets on one or more specified VLANs
+ specified in the <ref column="trunks"/> column (often, on every
+ VLAN). A packet that ingresses on a trunk port is in the VLAN
+ specified in its 802.1Q header, or VLAN 0 if the packet has no
+ 802.1Q header. A packet that egresses through a trunk port will
+ have an 802.1Q header if it has a nonzero VLAN ID.
+ </p>
+
+ <p>
+ Any packet that ingresses on a trunk port tagged with a VLAN that
+ the port does not trunk is dropped.
+ </p>
+ </dd>
+
+ <dt>access</dt>
+ <dd>
+ <p>
+ An access port carries packets on exactly one VLAN specified in the
+ <ref column="tag"/> column. Packets egressing on an access port
+ have no 802.1Q header.
+ </p>
+
+ <p>
+ Any packet with an 802.1Q header with a nonzero VLAN ID that
+ ingresses on an access port is dropped, regardless of whether the
+ VLAN ID in the header is the access port's VLAN ID.
+ </p>
+ </dd>
+
+ <dt>native-tagged</dt>
+ <dd>
+ A native-tagged port resembles a trunk port, with the exception that
+ a packet without an 802.1Q header that ingresses on a native-tagged
+ port is in the ``native VLAN'' (specified in the <ref column="tag"/>
+ column).
+ </dd>
+
+ <dt>native-untagged</dt>
+ <dd>
+ A native-untagged port resembles a native-tagged port, with the
+ exception that a packet that egresses on a native-untagged port in
+ the native VLAN will not have an 802.1Q header.
+ </dd>
+ </dl>
+ <p>
+ A packet will only egress through bridge ports that carry the VLAN of
+ the packet, as described by the rules above.
+ </p>
+
+ <column name="vlan_mode">
+ <p>
+ The VLAN mode of the port, as described above. When this column is
+ empty, a default mode is selected as follows:
+ </p>
+ <ul>
+ <li>
+ If <ref column="tag"/> contains a value, the port is an access
+ port. The <ref column="trunks"/> column should be empty.
+ </li>
+ <li>
+ Otherwise, the port is a trunk port. The <ref column="trunks"/>
+ column value is honored if it is present.
+ </li>
+ </ul>
+ </column>
+
+ <column name="tag">
+ <p>
+ For an access port, the port's implicitly tagged VLAN. For a
+ native-tagged or native-untagged port, the port's native VLAN. Must
+ be empty if this is a trunk port.
+ </p>
+ </column>
+
+ <column name="trunks">
+ <p>
+ For a trunk, native-tagged, or native-untagged port, the 802.1Q VLAN
+ or VLANs 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>
+ A native-tagged or native-untagged port always trunks its native
+ VLAN, regardless of whether <ref column="trunks"/> includes that
+ VLAN.
+ </p>
+ </column>
+
+ <column name="other_config" key="priority-tags"
+ type='{"type": "boolean"}'>
+ <p>
+ An 802.1Q header contains two important pieces of information: a VLAN
+ ID and a priority. A frame with a zero VLAN ID, called a
+ ``priority-tagged'' frame, is supposed to be treated the same way as
+ a frame without an 802.1Q header at all (except for the priority).
+ </p>
+
+ <p>
+ However, some network elements ignore any frame that has 802.1Q
+ header at all, even when the VLAN ID is zero. Therefore, by default
+ Open vSwitch does not output priority-tagged frames, instead omitting
+ the 802.1Q header entirely if the VLAN ID is zero. Set this key to
+ <code>true</code> to enable priority-tagged frames on a port.
+ </p>
+
+ <p>
+ Regardless of this setting, Open vSwitch omits the 802.1Q header on
+ output if both the VLAN ID and priority would be zero.
+ </p>
+
+ <p>
+ All frames output to native-tagged ports have a nonzero VLAN ID, so
+ this setting is not meaningful on native-tagged ports.
+ </p>
+ </column>
+ </group>
+
+ <group title="Bonding Configuration">
+ <p>A port that has more than one interface is a ``bonded port.'' Bonding
+ allows for load balancing and fail-over.</p>
+
+ <p>
+ The following types of bonding will work with any kind of upstream
+ switch. On the upstream switch, do not configure the interfaces as a
+ bond:
+ </p>
+
+ <dl>
+ <dt><code>balance-slb</code></dt>
+ <dd>
+ Balances flows among slaves based on source MAC address and output
+ VLAN, with periodic rebalancing as traffic patterns change.
+ </dd>
<dt><code>active-backup</code></dt>
<dd>
Assigns all flows to one slave, failing over to a backup slave when
- the active slave is disabled.
+ the active slave is disabled. This is the only bonding mode in which
+ interfaces may be plugged into different upstream switches.
</dd>
</dl>
<p>
- The following modes require the upstream switch to support 802.3ad with
- successful LACP negotiation. If LACP negotiation fails then
- <code>balance-slb</code> style flow hashing is used as a fallback:
+ The following modes require the upstream switch to support 802.3ad with
+ successful LACP negotiation. If LACP negotiation fails and
+ other-config:lacp-fallback-ab is true, then <code>active-backup</code>
+ mode is used:
+ </p>
+
+ <dl>
+ <dt><code>balance-tcp</code></dt>
+ <dd>
+ Balances flows among slaves based on L2, L3, and L4 protocol
+ information such as destination MAC address, IP address, and TCP
+ port.
+ </dd>
+ </dl>
+
+ <p>These columns apply only to bonded ports. Their values are
+ otherwise ignored.</p>
+
+ <column name="bond_mode">
+ <p>The type of bonding used for a bonded port. Defaults to
+ <code>active-backup</code> if unset.
+ </p>
+ </column>
+
+ <column name="other_config" key="bond-hash-basis"
+ type='{"type": "integer"}'>
+ An integer hashed along with flows when choosing output slaves in load
+ balanced bonds. When changed, all flows will be assigned different
+ hash values possibly causing slave selection decisions to change. Does
+ not affect bonding modes which do not employ load balancing such as
+ <code>active-backup</code>.
+ </column>
+
+ <group title="Link Failure Detection">
+ <p>
+ An important part of link bonding is detecting that links are down so
+ that they may be disabled. These settings determine how Open vSwitch
+ detects link failure.
+ </p>
+
+ <column name="other_config" key="bond-detect-mode"
+ type='{"type": "string", "enum": ["set", ["carrier", "miimon"]]}'>
+ The means used to detect link failures. Defaults to
+ <code>carrier</code> which uses each interface's carrier to detect
+ failures. When set to <code>miimon</code>, will check for failures
+ by polling each interface's MII.
+ </column>
+
+ <column name="other_config" key="bond-miimon-interval"
+ type='{"type": "integer"}'>
+ The interval, in milliseconds, between successive attempts to poll
+ each interface's MII. Relevant only when <ref column="other_config"
+ key="bond-detect-mode"/> is <code>miimon</code>.
+ </column>
+
+ <column name="bond_updelay">
+ <p>
+ The number of milliseconds for which the link must stay up on an
+ interface before the interface is considered to be up. Specify
+ <code>0</code> to enable the interface immediately.
+ </p>
+
+ <p>
+ This setting is honored only when at least one bonded interface is
+ already enabled. When no interfaces are enabled, then the first
+ bond interface to come up is enabled immediately.
+ </p>
+ </column>
+
+ <column name="bond_downdelay">
+ The number of milliseconds for which the link must stay down on an
+ interface before the interface is considered to be down. Specify
+ <code>0</code> to disable the interface immediately.
+ </column>
+ </group>
+
+ <group title="LACP Configuration">
+ <p>
+ LACP, the Link Aggregation Control Protocol, is an IEEE standard that
+ allows switches to automatically detect that they are connected by
+ multiple links and aggregate across those links. These settings
+ control LACP behavior.
+ </p>
+
+ <column name="lacp">
+ Configures LACP on this port. LACP allows directly connected
+ switches to negotiate which links may be bonded. LACP may be enabled
+ on non-bonded ports for the benefit of any switches they may be
+ connected to. <code>active</code> ports are allowed to initiate LACP
+ negotiations. <code>passive</code> ports are allowed to participate
+ in LACP negotiations initiated by a remote switch, but not allowed to
+ initiate such negotiations themselves. If LACP is enabled on a port
+ whose partner switch does not support LACP, the bond will be
+ disabled, unless other-config:lacp-fallback-ab is set to true.
+ Defaults to <code>off</code> if unset.
+ </column>
+
+ <column name="other_config" key="lacp-system-id">
+ The LACP system ID of this <ref table="Port"/>. The system ID of a
+ LACP bond is used to identify itself to its partners. Must be a
+ nonzero MAC address. Defaults to the bridge Ethernet address if
+ unset.
+ </column>
+
+ <column name="other_config" key="lacp-system-priority"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP system priority of this <ref table="Port"/>. In LACP
+ negotiations, link status decisions are made by the system with the
+ numerically lower priority.
+ </column>
+
+ <column name="other_config" key="lacp-time"
+ type='{"type": "string", "enum": ["set", ["fast", "slow"]]}'>
+ <p>
+ The LACP timing which should be used on this <ref table="Port"/>.
+ By default <code>slow</code> is used. When configured to be
+ <code>fast</code> LACP heartbeats are requested at a rate of once
+ per second causing connectivity problems to be detected more
+ quickly. In <code>slow</code> mode, heartbeats are requested at a
+ rate of once every 30 seconds.
+ </p>
+ </column>
+
+ <column name="other_config" key="lacp-fallback-ab"
+ type='{"type": "boolean"}'>
+ <p>
+ Determines the behavior of openvswitch bond in LACP mode. If
+ the partner switch does not support LACP, setting this option
+ to <code>true</code> allows openvswitch to fallback to
+ active-backup. If the option is set to <code>false</code>, the
+ bond will be disabled. In both the cases, once the partner switch
+ is configured to LACP mode, the bond will use LACP.
+ </p>
+ </column>
+ </group>
+
+ <group title="Rebalancing Configuration">
+ <p>
+ These settings control behavior when a bond is in
+ <code>balance-slb</code> or <code>balance-tcp</code> mode.
+ </p>
+
+ <column name="other_config" key="bond-rebalance-interval"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 10000}'>
+ For a load balanced bonded port, the number of milliseconds between
+ successive attempts to rebalance the bond, that is, to move flows
+ from one interface on the bond to another in an attempt to keep usage
+ of each interface roughly equal. If zero, load balancing is disabled
+ on the bond (link failure still cause flows to move). If
+ less than 1000ms, the rebalance interval will be 1000ms.
+ </column>
+ </group>
+
+ <column name="bond_fake_iface">
+ For a bonded port, whether to create a fake internal interface with the
+ name of the port. Use only for compatibility with legacy software that
+ requires this.
+ </column>
+ </group>
+
+ <group title="Spanning Tree Protocol">
+ <p>
+ The configuration here is only meaningful, and the status is only
+ populated, when 802.1D-1998 Spanning Tree Protocol is enabled on the
+ port's <ref column="Bridge"/> with its <ref column="stp_enable"/>
+ column.
+ </p>
+
+ <group title="STP Configuration">
+ <column name="other_config" key="stp-enable"
+ type='{"type": "boolean"}'>
+ When STP is enabled on a bridge, it is enabled by default on all of
+ the bridge's ports except bond, internal, and mirror ports (which do
+ not work with STP). If this column's value is <code>false</code>,
+ STP is disabled on the port.
+ </column>
+
+ <column name="other_config" key="stp-port-num"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 255}'>
+ The port number used for the lower 8 bits of the port-id. By
+ default, the numbers will be assigned automatically. If any
+ port's number is manually configured on a bridge, then they
+ must all be.
+ </column>
+
+ <column name="other_config" key="stp-port-priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 255}'>
+ The port's relative priority value for determining the root
+ port (the upper 8 bits of the port-id). A port with a lower
+ port-id will be chosen as the root port. By default, the
+ priority is 0x80.
+ </column>
+
+ <column name="other_config" key="stp-path-cost"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
+ Spanning tree path cost for the port. A lower number indicates
+ a faster link. By default, the cost is based on the maximum
+ speed of the link.
+ </column>
+ </group>
+
+ <group title="STP Status">
+ <column name="status" key="stp_port_id">
+ The port ID used in spanning tree advertisements for this port, as 4
+ hex digits. Configuring the port ID is described in the
+ <code>stp-port-num</code> and <code>stp-port-priority</code> keys of
+ the <code>other_config</code> section earlier.
+ </column>
+ <column name="status" key="stp_state"
+ type='{"type": "string", "enum": ["set",
+ ["disabled", "listening", "learning",
+ "forwarding", "blocking"]]}'>
+ STP state of the port.
+ </column>
+ <column name="status" key="stp_sec_in_state"
+ type='{"type": "integer", "minInteger": 0}'>
+ The amount of time this port has been in the current STP state, in
+ seconds.
+ </column>
+ <column name="status" key="stp_role"
+ type='{"type": "string", "enum": ["set",
+ ["root", "designated", "alternate"]]}'>
+ STP role of the port.
+ </column>
+ </group>
+ </group>
+
+ <group title="Rapid Spanning Tree Protocol">
+ <p>
+ The configuration here is only meaningful, and the status and
+ statistics are only populated, when 802.1D-1998 Spanning Tree Protocol
+ is enabled on the port's <ref column="Bridge"/> with its <ref
+ column="stp_enable"/> column.
+ </p>
+
+ <group title="RSTP Configuration">
+ <column name="other_config" key="rstp-enable"
+ type='{"type": "boolean"}'>
+ When RSTP is enabled on a bridge, it is enabled by default on all of
+ the bridge's ports except bond, internal, and mirror ports (which do
+ not work with RSTP). If this column's value is <code>false</code>,
+ RSTP is disabled on the port.
+ </column>
+
+ <column name="other_config" key="rstp-port-priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 240}'>
+ The port's relative priority value for determining the root port, in
+ multiples of 16. By default, the port priority is 0x80 (128). Any
+ value in the lower 4 bits is rounded off. The significant upper 4
+ bits become the upper 4 bits of the port-id. A port with the lowest
+ port-id is elected as the root.
+ </column>
+
+ <column name="other_config" key="rstp-port-num"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
+ The local RSTP port number, used as the lower 12 bits of the port-id.
+ By default the port numbers are assigned automatically, and typically
+ may not correspond to the OpenFlow port numbers. A port with the
+ lowest port-id is elected as the root.
+ </column>
+
+ <column name="other_config" key="rstp-port-path-cost"
+ type='{"type": "integer"}'>
+ The port path cost. The Port's contribution, when it is
+ the Root Port, to the Root Path Cost for the Bridge. By default the
+ cost is automatically calculated from the port's speed.
+ </column>
+
+ <column name="other_config" key="rstp-port-admin-edge"
+ type='{"type": "boolean"}'>
+ The admin edge port parameter for the Port. Default is
+ <code>false</code>.
+ </column>
+
+ <column name="other_config" key="rstp-port-auto-edge"
+ type='{"type": "boolean"}'>
+ The auto edge port parameter for the Port. Default is
+ <code>true</code>.
+ </column>
+
+ <column name="other_config" key="rstp-port-mcheck"
+ type='{"type": "boolean"}'>
+ <p>
+ The mcheck port parameter for the Port. Default is
+ <code>false</code>. May be set to force the Port Protocol
+ Migration state machine to transmit RST BPDUs for a
+ MigrateTime period, to test whether all STP Bridges on the
+ attached LAN have been removed and the Port can continue to
+ transmit RSTP BPDUs. Setting mcheck has no effect if the
+ Bridge is operating in STP Compatibility mode.
+ </p>
+ <p>
+ Changing the value from <code>true</code> to
+ <code>false</code> has no effect, but needs to be done if
+ this behavior is to be triggered again by subsequently
+ changing the value from <code>false</code> to
+ <code>true</code>.
+ </p>
+ </column>
+ </group>
+
+ <group title="RSTP Status">
+ <column name="rstp_status" key="rstp_port_id">
+ The port ID used in spanning tree advertisements for this port, as 4
+ hex digits. Configuring the port ID is described in the
+ <code>rstp-port-num</code> and <code>rstp-port-priority</code> keys
+ of the <code>other_config</code> section earlier.
+ </column>
+ <column name="rstp_status" key="rstp_port_role"
+ type='{"type": "string", "enum": ["set",
+ ["Root", "Designated", "Alternate", "Backup", "Disabled"]]}'>
+ RSTP role of the port.
+ </column>
+ <column name="rstp_status" key="rstp_port_state"
+ type='{"type": "string", "enum": ["set",
+ ["Disabled", "Learning", "Forwarding", "Discarding"]]}'>
+ RSTP state of the port.
+ </column>
+ <column name="rstp_status" key="rstp_designated_bridge_id">
+ The port's RSTP designated bridge ID, in the same form as <ref
+ column="rstp_status" key="rstp_bridge_id"/> in the <ref
+ table="Bridge"/> table.
+ </column>
+ <column name="rstp_status" key="rstp_designated_port_id">
+ The port's RSTP designated port ID, as 4 hex digits.
+ </column>
+ <column name="rstp_status" key="rstp_designated_path_cost"
+ type='{"type": "integer"}'>
+ The port's RSTP designated path cost. Lower is better.
+ </column>
+ </group>
+
+ <group title="RSTP Statistics">
+ <column name="rstp_statistics" key="rstp_tx_count">
+ Number of RSTP BPDUs transmitted through this port.
+ </column>
+ <column name="rstp_statistics" key="rstp_rx_count">
+ Number of valid RSTP BPDUs received by this port.
+ </column>
+ <column name="rstp_statistics" key="rstp_error_count">
+ Number of invalid RSTP BPDUs received by this port.
+ </column>
+ <column name="rstp_statistics" key="rstp_uptime">
+ The duration covered by the other RSTP statistics, in seconds.
+ </column>
+ </group>
+ </group>
+
+ <group title="Multicast Snooping">
+ <column name="other_config" key="mcast-snooping-flood"
+ type='{"type": "boolean"}'>
+ <p>
+ If set to <code>true</code>, multicast packets (except Reports) are
+ unconditionally forwarded to the specific port.
+ </p>
+ </column>
+ <column name="other_config" key="mcast-snooping-flood-reports"
+ type='{"type": "boolean"}'>
+ <p>
+ If set to <code>true</code>, multicast Reports are unconditionally
+ forwarded to the specific port.
+ </p>
+ </column>
+ </group>
+
+ <group title="Other Features">
+ <column name="qos">
+ Quality of Service configuration for this port.
+ </column>
+
+ <column name="mac">
+ The MAC address to use for this port for the purpose of choosing the
+ bridge's MAC address. This column does not necessarily reflect the
+ port's actual MAC address, nor will setting it change the port's actual
+ MAC address.
+ </column>
+
+ <column name="fake_bridge">
+ Does this port represent a sub-bridge for its tagged VLAN within the
+ Bridge? See ovs-vsctl(8) for more information.
+ </column>
+
+ <column name="external_ids" key="fake-bridge-id-*">
+ External IDs for a fake bridge (see the <ref column="fake_bridge"/>
+ column) are defined 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>.
+ </column>
+
+ <column name="other_config" key="transient"
+ type='{"type": "boolean"}'>
+ <p>
+ If set to <code>true</code>, the port will be removed when
+ <code>ovs-ctl start --delete-transient-ports</code> is used.
+ </p>
+ </column>
+ </group>
+
+ <column name="bond_active_slave">
+ For a bonded port, record the mac address of the current active slave.
+ </column>
+
+ <group title="Port Statistics">
+ <p>
+ Key-value pairs that report port statistics. The update period
+ is controlled by <ref column="other_config"
+ key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
+ </p>
+ <group title="Statistics: STP transmit and receive counters">
+ <column name="statistics" key="stp_tx_count">
+ Number of STP BPDUs sent on this port by the spanning
+ tree library.
+ </column>
+ <column name="statistics" key="stp_rx_count">
+ Number of STP BPDUs received on this port and accepted by the
+ spanning tree library.
+ </column>
+ <column name="statistics" key="stp_error_count">
+ Number of bad STP BPDUs received on this port. Bad BPDUs
+ include runt packets and those with an unexpected protocol ID.
+ </column>
+ </group>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Interface" title="One physical network device in a Port.">
+ An interface within a <ref table="Port"/>.
+
+ <group title="Core Features">
+ <column name="name">
+ Interface name. Should be alphanumeric and no more than about 8 bytes
+ long. May be the same as the port name, for non-bonded ports. Must
+ otherwise be unique among the names of ports, interfaces, and bridges
+ on a host.
+ </column>
+
+ <column name="ifindex">
+ A positive interface index as defined for SNMP MIB-II in RFCs 1213 and
+ 2863, if the interface has one, otherwise 0. The ifindex is useful for
+ seamless integration with protocols such as SNMP and sFlow.
+ </column>
+
+ <column name="mac_in_use">
+ The MAC address in use by this interface.
+ </column>
+
+ <column name="mac">
+ <p>Ethernet address to set for this interface. If unset then the
+ default MAC address is used:</p>
+ <ul>
+ <li>For the local interface, the default is the lowest-numbered MAC
+ address among the other bridge ports, either the value of the
+ <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
+ if set, or its actual MAC (for bonded ports, the MAC of its slave
+ whose name is first in alphabetical order). Internal ports and
+ bridge ports that are used as port mirroring destinations (see the
+ <ref table="Mirror"/> table) are ignored.</li>
+ <li>For other internal interfaces, the default MAC is randomly
+ generated.</li>
+ <li>External interfaces typically have a MAC address associated with
+ their hardware.</li>
+ </ul>
+ <p>Some interfaces may not have a software-controllable MAC
+ address.</p>
+ </column>
+
+ <column name="error">
+ If the configuration of the port failed, as indicated by -1 in <ref
+ column="ofport"/>, Open vSwitch sets this column to an error
+ description in human readable form. Otherwise, Open vSwitch clears
+ this column.
+ </column>
+
+ <group title="OpenFlow Port Number">
+ <p>
+ When a client adds a new interface, Open vSwitch chooses an OpenFlow
+ port number for the new port. If the client that adds the port fills
+ in <ref column="ofport_request"/>, then Open vSwitch tries to use its
+ value as the OpenFlow port number. Otherwise, or if the requested
+ port number is already in use or cannot be used for another reason,
+ Open vSwitch automatically assigns a free port number. Regardless of
+ how the port number was obtained, Open vSwitch then reports in <ref
+ column="ofport"/> the port number actually assigned.
+ </p>
+
+ <p>
+ Open vSwitch limits the port numbers that it automatically assigns to
+ the range 1 through 32,767, inclusive. Controllers therefore have
+ free use of ports 32,768 and up.
+ </p>
+
+ <column name="ofport">
+ <p>
+ OpenFlow port number for this interface. Open vSwitch sets this
+ column's value, so other clients should treat it as read-only.
+ </p>
+ <p>
+ The OpenFlow ``local'' port (<code>OFPP_LOCAL</code>) is 65,534.
+ The other valid port numbers are in the range 1 to 65,279,
+ inclusive. Value -1 indicates an error adding the interface.
+ </p>
+ </column>
+
+ <column name="ofport_request"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65279}'>
+ <p>
+ Requested OpenFlow port number for this interface.
+ </p>
+
+ <p>
+ A client should ideally set this column's value in the same
+ database transaction that it uses to create the interface. Open
+ vSwitch version 2.1 and later will honor a later request for a
+ specific port number, althuogh it might confuse some controllers:
+ OpenFlow does not have a way to announce a port number change, so
+ Open vSwitch represents it over OpenFlow as a port deletion
+ followed immediately by a port addition.
+ </p>
+
+ <p>
+ If <ref column="ofport_request"/> is set or changed to some other
+ port's automatically assigned port number, Open vSwitch chooses a
+ new port number for the latter port.
+ </p>
+ </column>
+ </group>
+ </group>
+
+ <group title="System-Specific Details">
+ <column name="type">
+ <p>
+ The interface type. The types supported by a particular instance of
+ Open vSwitch are listed in the <ref table="Open_vSwitch"
+ column="iface_types"/> column in the <ref table="Open_vSwitch"/>
+ table. The following types are defined:
+ </p>
+
+ <dl>
+ <dt><code>system</code></dt>
+ <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
+ Sometimes referred to as ``external interfaces'' since they are
+ generally connected to hardware external to that on which the Open
+ vSwitch is running. The empty string is a synonym for
+ <code>system</code>.</dd>
+
+ <dt><code>internal</code></dt>
+ <dd>A simulated network device that sends and receives traffic. An
+ internal interface whose <ref column="name"/> is the same as its
+ bridge's <ref table="Open_vSwitch" column="name"/> is called the
+ ``local interface.'' It does not make sense to bond an internal
+ interface, so the terms ``port'' and ``interface'' are often used
+ imprecisely for internal interfaces.</dd>
+
+ <dt><code>tap</code></dt>
+ <dd>A TUN/TAP device managed by Open vSwitch.</dd>
+
+ <dt><code>geneve</code></dt>
+ <dd>
+ An Ethernet over Geneve (<code>http://tools.ietf.org/html/draft-ietf-nvo3-geneve-00</code>)
+ IPv4 tunnel.
+
+ A description of how to match and set Geneve options can be found
+ in the <code>ovs-ofctl</code> manual page.
+ </dd>
+
+ <dt><code>gre</code></dt>
+ <dd>
+ An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
+ tunnel.
+ </dd>
+
+ <dt><code>ipsec_gre</code></dt>
+ <dd>
+ An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
+ IPsec tunnel.
+ </dd>
+
+ <dt><code>vxlan</code></dt>
+ <dd>
+ <p>
+ An Ethernet tunnel over the UDP-based VXLAN protocol described in
+ RFC 7348.
+ </p>
+ <p>
+ Open vSwitch uses UDP destination port 4789. The source port used for
+ VXLAN traffic varies on a per-flow basis and is in the ephemeral port
+ range.
+ </p>
+ </dd>
+
+ <dt><code>lisp</code></dt>
+ <dd>
+ <p>
+ A layer 3 tunnel over the experimental, UDP-based Locator/ID
+ Separation Protocol (RFC 6830).
+ </p>
+ <p>
+ Only IPv4 and IPv6 packets are supported by the protocol, and
+ they are sent and received without an Ethernet header. Traffic
+ to/from LISP ports is expected to be configured explicitly, and
+ the ports are not intended to participate in learning based
+ switching. As such, they are always excluded from packet
+ flooding.
+ </p>
+ </dd>
+
+ <dt><code>stt</code></dt>
+ <dd>
+ The Stateless TCP Tunnel (STT) is particularly useful when tunnel
+ endpoints are in end-systems, as it utilizes the capabilities of
+ standard network interface cards to improve performance. STT utilizes
+ a TCP-like header inside the IP header. It is stateless, i.e., there is
+ no TCP connection state of any kind associated with the tunnel. The
+ TCP-like header is used to leverage the capabilities of existing
+ network interface cards, but should not be interpreted as implying
+ any sort of connection state between endpoints.
+ Since the STT protocol does not engage in the usual TCP 3-way handshake,
+ so it will have difficulty traversing stateful firewalls.
+ The protocol is documented at
+ http://www.ietf.org/archive/id/draft-davie-stt-06.txt
+
+ All traffic uses a default destination port of 7471. STT is only
+ available in kernel datapath on kernel 3.5 or newer.
+ </dd>
+
+ <dt><code>patch</code></dt>
+ <dd>
+ A pair of virtual devices that act as a patch cable.
+ </dd>
+
+ <dt><code>null</code></dt>
+ <dd>An ignored interface. Deprecated and slated for removal in
+ February 2013.</dd>
+ </dl>
+ </column>
+ </group>
+
+ <group title="Tunnel Options">
+ <p>
+ These options apply to interfaces with <ref column="type"/> of
+ <code>geneve</code>, <code>gre</code>, <code>ipsec_gre</code>,
+ <code>vxlan</code>, <code>lisp</code> and <code>stt</code>.
+ </p>
+
+ <p>
+ Each tunnel must be uniquely identified by the combination of <ref
+ column="type"/>, <ref column="options" key="remote_ip"/>, <ref
+ column="options" key="local_ip"/>, and <ref column="options"
+ key="in_key"/>. 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. <ref column="options" key="in_key"/> is
+ considered more specific than <ref column="options" key="local_ip"/> if
+ a port defines one and another port defines the other.
+ </p>
+
+ <column name="options" key="remote_ip">
+ <p>Required. The remote tunnel endpoint, one of:</p>
+
+ <ul>
+ <li>
+ An IPv4 address (not a DNS name), e.g. <code>192.168.0.123</code>.
+ Only unicast endpoints are supported.
+ </li>
+ <li>
+ The word <code>flow</code>. The tunnel accepts packets from any
+ remote tunnel endpoint. To process only packets from a specific
+ remote tunnel endpoint, the flow entries may match on the
+ <code>tun_src</code> field. When sending packets to a
+ <code>remote_ip=flow</code> tunnel, the flow actions must
+ explicitly set the <code>tun_dst</code> field to the IP address of
+ the desired remote tunnel endpoint, e.g. with a
+ <code>set_field</code> action.
+ </li>
+ </ul>
+
+ <p>
+ The remote tunnel endpoint for any packet received from a tunnel
+ is available in the <code>tun_src</code> field for matching in the
+ flow table.
+ </p>
+ </column>
+
+ <column name="options" key="local_ip">
+ <p>
+ Optional. The tunnel destination IP that received packets must
+ match. Default is to match all addresses. If specified, may be one
+ of:
+ </p>
+
+ <ul>
+ <li>
+ An IPv4 address (not a DNS name), e.g. <code>192.168.12.3</code>.
+ </li>
+ <li>
+ The word <code>flow</code>. The tunnel accepts packets sent to any
+ of the local IP addresses of the system running OVS. To process
+ only packets sent to a specific IP address, the flow entries may
+ match on the <code>tun_dst</code> field. When sending packets to a
+ <code>local_ip=flow</code> tunnel, the flow actions may
+ explicitly set the <code>tun_src</code> field to the desired IP
+ address, e.g. with a <code>set_field</code> action. However, while
+ routing the tunneled packet out, the local system may override the
+ specified address with the local IP address configured for the
+ outgoing system interface.
+
+ <p>
+ This option is valid only for tunnels also configured with the
+ <code>remote_ip=flow</code> option.
+ </p>
+ </li>
+ </ul>
+
+ <p>
+ The tunnel destination IP address for any packet received from a
+ tunnel is available in the <code>tun_dst</code> field for matching in
+ the flow table.
+ </p>
+ </column>
+
+ <column name="options" key="in_key">
+ <p>Optional. The key that received packets must contain, one of:</p>
+
+ <ul>
+ <li>
+ <code>0</code>. The tunnel receives packets with no key or with a
+ key of 0. This is equivalent to specifying no <ref column="options"
+ key="in_key"/> at all.
+ </li>
+ <li>
+ A positive 24-bit (for Geneve, VXLAN, and LISP), 32-bit (for GRE)
+ or 64-bit (for STT) number. The tunnel receives only
+ packets with the specified key.
+ </li>
+ <li>
+ The word <code>flow</code>. The tunnel accepts packets with any
+ key. The key will be placed in the <code>tun_id</code> field for
+ matching in the flow table. The <code>ovs-ofctl</code> manual page
+ contains additional information about matching fields in OpenFlow
+ flows.
+ </li>
+ </ul>
+
+ <p>
+ </p>
+ </column>
+
+ <column name="options" key="out_key">
+ <p>Optional. The key to be set on outgoing packets, one of:</p>
+
+ <ul>
+ <li>
+ <code>0</code>. Packets sent through the tunnel will have no key.
+ This is equivalent to specifying no <ref column="options"
+ key="out_key"/> at all.
+ </li>
+ <li>
+ A positive 24-bit (for Geneve, VXLAN and LISP), 32-bit (for GRE) or
+ 64-bit (for STT) number. Packets sent through the tunnel
+ will have the specified key.
+ </li>
+ <li>
+ The word <code>flow</code>. Packets sent through the tunnel will
+ have the key set using the <code>set_tunnel</code> Nicira OpenFlow
+ vendor extension (0 is used in the absence of an action). The
+ <code>ovs-ofctl</code> manual page contains additional information
+ about the Nicira OpenFlow vendor extensions.
+ </li>
+ </ul>
+ </column>
+
+ <column name="options" key="key">
+ Optional. Shorthand to set <code>in_key</code> and
+ <code>out_key</code> at the same time.
+ </column>
+
+ <column name="options" key="tos">
+ Optional. The value of the ToS bits to be set on the encapsulating
+ packet. ToS is interpreted as DSCP and ECN bits, ECN part must be
+ zero. 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). The ECN fields are always inherited.
+ Default is 0.
+ </column>
+
+ <column name="options" key="ttl">
+ 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.
+ </column>
+
+ <column name="options" key="df_default"
+ type='{"type": "boolean"}'>
+ Optional. If enabled, the Don't Fragment bit will be set on tunnel
+ outer headers to allow path MTU discovery. Default is enabled; set
+ to <code>false</code> to disable.
+ </column>
+
+ <group title="Tunnel Options: vxlan only">
+
+ <column name="options" key="exts">
+ <p>Optional. Comma separated list of optional VXLAN extensions to
+ enable. The following extensions are supported:</p>
+
+ <ul>
+ <li>
+ <code>gbp</code>: VXLAN-GBP allows to transport the group policy
+ context of a packet across the VXLAN tunnel to other network
+ peers. See the field description of <code>tun_gbp_id</code> and
+ <code>tun_gbp_flags</code> in ovs-ofctl(8) for additional
+ information.
+ (<code>https://tools.ietf.org/html/draft-smith-vxlan-group-policy</code>)
+ </li>
+ </ul>
+ </column>
+
+ </group>
+
+ <group title="Tunnel Options: gre, ipsec_gre, geneve, and vxlan">
+ <p>
+ <code>gre</code>, <code>ipsec_gre</code>, <code>geneve</code>, and
+ <code>vxlan</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="csum" type='{"type": "boolean"}'>
+ <p>
+ Optional. Compute encapsulation header (either GRE or UDP)
+ checksums on outgoing packets. Default is disabled, set to
+ <code>true</code> to enable. Checksums present on incoming
+ packets will be validated regardless of this setting.
+ </p>
+
+ <p>
+ When using the upstream Linux kernel module, computation of
+ checksums for <code>geneve</code> and <code>vxlan</code> requires
+ Linux kernel version 4.0 or higher. <code>gre</code> supports
+ checksums for all versions of Open vSwitch that support GRE.
+ The out of tree kernel module distributed as part of OVS
+ can compute all tunnel checksums on any kernel version that it
+ is compatible with.
+ </p>
+
+ <p>
+ This option is supported for <code>ipsec_gre</code>, but not useful
+ because GRE checksums are weaker than, and redundant with, IPsec
+ payload authentication.
+ </p>
+ </column>
+ </group>
+
+ <group title="Tunnel Options: ipsec_gre only">
+ <p>
+ Only <code>ipsec_gre</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer_cert">
+ Required for certificate authentication. A string containing the
+ peer's certificate in PEM format. Additionally the host's
+ certificate must be specified with the <code>certificate</code>
+ option.
+ </column>
+
+ <column name="options" key="certificate">
+ Required for certificate authentication. The name of a PEM file
+ containing a certificate that will be presented to the peer during
+ authentication.
+ </column>
+
+ <column name="options" key="private_key">
+ Optional for certificate authentication. The name of a PEM file
+ containing the private key associated with <code>certificate</code>.
+ If <code>certificate</code> contains the private key, this option may
+ be omitted.
+ </column>
+
+ <column name="options" key="psk">
+ Required for pre-shared key authentication. Specifies a pre-shared
+ key for authentication that must be identical on both sides of the
+ tunnel.
+ </column>
+ </group>
+ </group>
+
+ <group title="Patch Options">
+ <p>
+ Only <code>patch</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer">
+ The <ref column="name"/> of the <ref table="Interface"/> for the other
+ side of the patch. The named <ref table="Interface"/>'s own
+ <code>peer</code> option must specify this <ref table="Interface"/>'s
+ name. That is, the two patch interfaces must have reversed <ref
+ column="name"/> and <code>peer</code> values.
+ </column>
+ </group>
+
+ <group title="PMD (Poll Mode Driver) Options">
+ <p>
+ Only PMD netdevs support these options.
+ </p>
+
+ <column name="options" key="n_rxqs"
+ type='{"type": "integer", "minInteger": 1}'>
+ <p>
+ Specifies the maximum number of rx queues to be created for PMD
+ netdev. If not specified or specified to 0, one rx queue will
+ be created by default.
+ </p>
+ </column>
+ </group>
+
+ <group title="Interface Status">
+ <p>
+ Status information about interfaces attached to bridges, updated every
+ 5 seconds. Not all interfaces have all of these properties; virtual
+ interfaces don't have a link speed, for example. Non-applicable
+ columns will have empty values.
+ </p>
+ <column name="admin_state">
+ <p>
+ The administrative state of the physical network link.
+ </p>
+ </column>
+
+ <column name="link_state">
+ <p>
+ The observed state of the physical network link. This is ordinarily
+ the link's carrier status. If the interface's <ref table="Port"/> is
+ a bond configured for miimon monitoring, it is instead the network
+ link's miimon status.
+ </p>
+ </column>
+
+ <column name="link_resets">
+ <p>
+ The number of times Open vSwitch has observed the
+ <ref column="link_state"/> of this <ref table="Interface"/> change.
+ </p>
+ </column>
+
+ <column name="link_speed">
+ <p>
+ The negotiated speed of the physical network link.
+ Valid values are positive integers greater than 0.
+ </p>
+ </column>
+
+ <column name="duplex">
+ <p>
+ The duplex mode of the physical network link.
+ </p>
+ </column>
+
+ <column name="mtu">
+ <p>
+ The MTU (maximum transmission unit); i.e. the largest
+ amount of data that can fit into a single Ethernet frame.
+ The standard Ethernet MTU is 1500 bytes. Some physical media
+ and many kinds of virtual interfaces can be configured with
+ higher MTUs.
+ </p>
+ <p>
+ This column will be empty for an interface that does not
+ have an MTU as, for example, some kinds of tunnels do not.
+ </p>
+ </column>
+
+ <column name="lacp_current">
+ Boolean value indicating LACP status for this interface. If true, this
+ interface has current LACP information about its LACP partner. This
+ information may be used to monitor the health of interfaces in a LACP
+ enabled port. This column will be empty if LACP is not enabled.
+ </column>
+
+ <column name="status">
+ Key-value pairs that report port status. Supported status values are
+ <ref column="type"/>-dependent; some interfaces may not have a valid
+ <ref column="status" key="driver_name"/>, for example.
+ </column>
+
+ <column name="status" key="driver_name">
+ The name of the device driver controlling the network adapter.
+ </column>
+
+ <column name="status" key="driver_version">
+ The version string of the device driver controlling the network
+ adapter.
+ </column>
+
+ <column name="status" key="firmware_version">
+ The version string of the network adapter's firmware, if available.
+ </column>
+
+ <column name="status" key="source_ip">
+ The source IP address used for an IPv4 tunnel end-point, such as
+ <code>gre</code>.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface">
+ Egress interface for tunnels. Currently only relevant for tunnels
+ on Linux systems, this column will show the name of the interface
+ which is responsible for routing traffic destined for the configured
+ <ref column="options" key="remote_ip"/>. This could be an internal
+ interface such as a bridge port.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface_carrier"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ Whether carrier is detected on <ref column="status"
+ key="tunnel_egress_iface"/>.
+ </column>
+ </group>
+
+ <group title="Statistics">
+ <p>
+ Key-value pairs that report interface statistics. The current
+ implementation updates these counters periodically. The update period
+ is controlled by <ref column="other_config"
+ key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
+ Future implementations may update them when an interface is created,
+ when they are queried (e.g. using an OVSDB <code>select</code>
+ operation), and just before an interface is deleted due to virtual
+ interface hot-unplug or VM shutdown, and perhaps at other times, but
+ not on any regular periodic basis.
+ </p>
+ <p>
+ These are the same statistics reported by OpenFlow in its <code>struct
+ ofp_port_stats</code> structure. If an interface does not support a
+ given statistic, then that pair is omitted.
+ </p>
+ <group title="Statistics: Successful transmit and receive counters">
+ <column name="statistics" key="rx_packets">
+ Number of received packets.
+ </column>
+ <column name="statistics" key="rx_bytes">
+ Number of received bytes.
+ </column>
+ <column name="statistics" key="tx_packets">
+ Number of transmitted packets.
+ </column>
+ <column name="statistics" key="tx_bytes">
+ Number of transmitted bytes.
+ </column>
+ </group>
+ <group title="Statistics: Receive errors">
+ <column name="statistics" key="rx_dropped">
+ Number of packets dropped by RX.
+ </column>
+ <column name="statistics" key="rx_frame_err">
+ Number of frame alignment errors.
+ </column>
+ <column name="statistics" key="rx_over_err">
+ Number of packets with RX overrun.
+ </column>
+ <column name="statistics" key="rx_crc_err">
+ Number of CRC errors.
+ </column>
+ <column name="statistics" key="rx_errors">
+ Total number of receive errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ <group title="Statistics: Transmit errors">
+ <column name="statistics" key="tx_dropped">
+ Number of packets dropped by TX.
+ </column>
+ <column name="statistics" key="collisions">
+ Number of collisions.
+ </column>
+ <column name="statistics" key="tx_errors">
+ Total number of transmit errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ </group>
+
+ <group title="Ingress Policing">
+ <p>
+ These settings control ingress policing for packets received on this
+ interface. On a physical interface, this limits the rate at which
+ traffic is allowed into the system from the outside; on a virtual
+ interface (one connected to a virtual machine), this limits the rate at
+ which the VM is able to transmit.
+ </p>
+ <p>
+ Policing is a simple form of quality-of-service that simply drops
+ packets received in excess of the configured rate. Due to its
+ simplicity, policing is usually less accurate and less effective than
+ egress QoS (which is configured using the <ref table="QoS"/> and <ref
+ table="Queue"/> tables).
+ </p>
+ <p>
+ Policing is currently implemented only on Linux. The Linux
+ implementation uses a simple ``token bucket'' approach:
+ </p>
+ <ul>
+ <li>
+ The size of the bucket corresponds to <ref
+ column="ingress_policing_burst"/>. Initially the bucket is full.
+ </li>
+ <li>
+ Whenever a packet is received, its size (converted to tokens) is
+ compared to the number of tokens currently in the bucket. If the
+ required number of tokens are available, they are removed and the
+ packet is forwarded. Otherwise, the packet is dropped.
+ </li>
+ <li>
+ Whenever it is not full, the bucket is refilled with tokens at the
+ rate specified by <ref column="ingress_policing_rate"/>.
+ </li>
+ </ul>
+ <p>
+ Policing interacts badly with some network protocols, and especially
+ with fragmented IP packets. Suppose that there is enough network
+ activity to keep the bucket nearly empty all the time. Then this token
+ bucket algorithm will forward a single packet every so often, with the
+ period depending on packet size and on the configured rate. All of the
+ fragments of an IP packets are normally transmitted back-to-back, as a
+ group. In such a situation, therefore, only one of these fragments
+ will be forwarded and the rest will be dropped. IP does not provide
+ any way for the intended recipient to ask for only the remaining
+ fragments. In such a case there are two likely possibilities for what
+ will happen next: either all of the fragments will eventually be
+ retransmitted (as TCP will do), in which case the same problem will
+ recur, or the sender will not realize that its packet has been dropped
+ and data will simply be lost (as some UDP-based protocols will do).
+ Either way, it is possible that no forward progress will ever occur.
+ </p>
+ <column name="ingress_policing_rate">
+ <p>
+ Maximum rate for data received on this interface, in kbps. Data
+ received faster than this rate is dropped. Set to <code>0</code>
+ (the default) to disable policing.
+ </p>
+ </column>
+
+ <column name="ingress_policing_burst">
+ <p>Maximum burst size for data received on this interface, in kb. The
+ default burst size if set to <code>0</code> is 1000 kb. This value
+ has no effect if <ref column="ingress_policing_rate"/>
+ is <code>0</code>.</p>
+ <p>
+ Specifying a larger burst size lets the algorithm be more forgiving,
+ which is important for protocols like TCP that react severely to
+ dropped packets. The burst size should be at least the size of the
+ interface's MTU. Specifying a value that is numerically at least as
+ large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
+ closer to achieving the full rate.
+ </p>
+ </column>
+ </group>
+
+ <group title="Bidirectional Forwarding Detection (BFD)">
+ <p>
+ BFD, defined in RFC 5880 and RFC 5881, allows point-to-point
+ detection of connectivity failures by occasional transmission of
+ BFD control messages. Open vSwitch implements BFD to serve
+ as a more popular and standards compliant alternative to CFM.
+ </p>
+
+ <p>
+ BFD operates by regularly transmitting BFD control messages at a rate
+ negotiated independently in each direction. Each endpoint specifies
+ the rate at which it expects to receive control messages, and the rate
+ at which it is willing to transmit them. Open vSwitch uses a detection
+ multiplier of three, meaning that an endpoint signals a connectivity
+ fault if three consecutive BFD control messages fail to arrive. In the
+ case of a unidirectional connectivity issue, the system not receiving
+ BFD control messages signals the problem to its peer in the messages it
+ transmits.
+ </p>
+
+ <p>
+ The Open vSwitch implementation of BFD aims to comply faithfully
+ with RFC 5880 requirements. Open vSwitch does not implement the
+ optional Authentication or ``Echo Mode'' features.
+ </p>
+
+ <group title="BFD Configuration">
+ <p>
+ A controller sets up key-value pairs in the <ref column="bfd"/>
+ column to enable and configure BFD.
+ </p>
+
+ <column name="bfd" key="enable" type='{"type": "boolean"}'>
+ True to enable BFD on this <ref table="Interface"/>. If not
+ specified, BFD will not be enabled by default.
+ </column>
+
+ <column name="bfd" key="min_rx"
+ type='{"type": "integer", "minInteger": 1}'>
+ The shortest interval, in milliseconds, at which this BFD session
+ offers to receive BFD control messages. The remote endpoint may
+ choose to send messages at a slower rate. Defaults to
+ <code>1000</code>.
+ </column>
+
+ <column name="bfd" key="min_tx"
+ type='{"type": "integer", "minInteger": 1}'>
+ The shortest interval, in milliseconds, at which this BFD session is
+ willing to transmit BFD control messages. Messages will actually be
+ transmitted at a slower rate if the remote endpoint is not willing to
+ receive as quickly as specified. Defaults to <code>100</code>.
+ </column>
+
+ <column name="bfd" key="decay_min_rx" type='{"type": "integer"}'>
+ An alternate receive interval, in milliseconds, that must be greater
+ than or equal to <ref column="bfd" key="min_rx"/>. The
+ implementation switches from <ref column="bfd" key="min_rx"/> to <ref
+ column="bfd" key="decay_min_rx"/> when there is no obvious incoming
+ data traffic at the interface, to reduce the CPU and bandwidth cost
+ of monitoring an idle interface. This feature may be disabled by
+ setting a value of 0. This feature is reset whenever <ref
+ column="bfd" key="decay_min_rx"/> or <ref column="bfd" key="min_rx"/>
+ changes.
+ </column>
+
+ <column name="bfd" key="forwarding_if_rx" type='{"type": "boolean"}'>
+ When <code>true</code>, traffic received on the
+ <ref table="Interface"/> is used to indicate the capability of packet
+ I/O. BFD control packets are still transmitted and received. At
+ least one BFD control packet must be received every 100 * <ref
+ column="bfd" key="min_rx"/> amount of time. Otherwise, even if
+ traffic are received, the <ref column="bfd" key="forwarding"/>
+ will be <code>false</code>.
+ </column>
+
+ <column name="bfd" key="cpath_down" type='{"type": "boolean"}'>
+ Set to true to notify the remote endpoint that traffic should not be
+ forwarded to this system for some reason other than a connectivty
+ failure on the interface being monitored. The typical underlying
+ reason is ``concatenated path down,'' that is, that connectivity
+ beyond the local system is down. Defaults to false.
+ </column>
+
+ <column name="bfd" key="check_tnl_key" type='{"type": "boolean"}'>
+ Set to true to make BFD accept only control messages with a tunnel
+ key of zero. By default, BFD accepts control messages with any
+ tunnel key.
+ </column>
+
+ <column name="bfd" key="bfd_local_src_mac">
+ Set to 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 MAC used as source for transmitted BFD packets. The
+ default is the mac address of the BFD enabled interface.
+ </column>
+
+ <column name="bfd" key="bfd_local_dst_mac">
+ Set to 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 MAC used as destination for transmitted BFD packets. The
+ default is <code>00:23:20:00:00:01</code>.
+ </column>
+
+ <column name="bfd" key="bfd_remote_dst_mac">
+ Set to 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 MAC used for checking the destination of received BFD packets.
+ Packets with different destination MAC will not be considered as BFD packets.
+ If not specified the destination MAC address of received BFD packets
+ are not checked.
+ </column>
+
+ <column name="bfd" key="bfd_src_ip">
+ Set to an IPv4 address to set the IP address used as source for
+ transmitted BFD packets. The default is <code>169.254.1.1</code>.
+ </column>
+
+ <column name="bfd" key="bfd_dst_ip">
+ Set to an IPv4 address to set the IP address used as destination
+ for transmitted BFD packets. The default is <code>169.254.1.0</code>.
+ </column>
+ </group>
+
+ <group title="BFD Status">
+ <p>
+ The switch sets key-value pairs in the <ref column="bfd_status"/>
+ column to report the status of BFD on this interface. When BFD is
+ not enabled, with <ref column="bfd" key="enable"/>, the switch clears
+ all key-value pairs from <ref column="bfd_status"/>.
+ </p>
+
+ <column name="bfd_status" key="state"
+ type='{"type": "string",
+ "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
+ Reports the state of the BFD session. The BFD session is fully
+ healthy and negotiated if <code>UP</code>.
+ </column>
+
+ <column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
+ Reports whether the BFD session believes this <ref
+ table="Interface"/> may be used to forward traffic. Typically this
+ means the local session is signaling <code>UP</code>, and the remote
+ system isn't signaling a problem such as concatenated path down.
+ </column>
+
+ <column name="bfd_status" key="diagnostic">
+ A diagnostic code specifying the local system's reason for the
+ last change in session state. The error messages are defined in
+ section 4.1 of [RFC 5880].
+ </column>
+
+ <column name="bfd_status" key="remote_state"
+ type='{"type": "string",
+ "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
+ Reports the state of the remote endpoint's BFD session.
+ </column>
+
+ <column name="bfd_status" key="remote_diagnostic">
+ A diagnostic code specifying the remote system's reason for the
+ last change in session state. The error messages are defined in
+ section 4.1 of [RFC 5880].
+ </column>
+
+ <column name="bfd_status" key="flap_count"
+ type='{"type": "integer", "minInteger": 0}'>
+ Counts the number of <ref column="bfd_status" key="forwarding" />
+ flaps since start. A flap is considered as a change of the
+ <ref column="bfd_status" key="forwarding" /> value.
+ </column>
+ </group>
+ </group>
+
+ <group title="Connectivity Fault Management">
+ <p>
+ 802.1ag Connectivity Fault Management (CFM) allows a group of
+ Maintenance Points (MPs) called a Maintenance Association (MA) to
+ detect connectivity problems with each other. MPs within a MA should
+ have complete and exclusive interconnectivity. This is verified by
+ occasionally broadcasting Continuity Check Messages (CCMs) at a
+ configurable transmission interval.
+ </p>
+
+ <p>
+ According to the 802.1ag specification, each Maintenance Point should
+ be configured out-of-band with a list of Remote Maintenance Points it
+ should have connectivity to. Open vSwitch differs from the
+ specification in this area. It simply assumes the link is faulted if
+ no Remote Maintenance Points are reachable, and considers it not
+ faulted otherwise.
+ </p>
+
+ <p>
+ When operating over tunnels which have no <code>in_key</code>, or an
+ <code>in_key</code> of <code>flow</code>. CFM will only accept CCMs
+ with a tunnel key of zero.
</p>
- <dl>
- <dt><code>balance-tcp</code></dt>
- <dd>
- Balances flows among slaves based on L2, L3, and L4 protocol
- information such as destination MAC address, IP address, and TCP
- port.
- </dd>
- </dl>
-
- <dl>
- <dt><code>stable</code></dt>
- <dd>
- <p>Attempts to always assign a given flow to the same slave
- consistently. In an effort to maintain stability, no load
- balancing is done. Uses a similar hashing strategy to
- <code>balance-tcp</code>, always taking into account L3 and L4
- fields even if LACP negotiations are unsuccessful. </p>
- <p>Slave selection decisions are made based on <ref table="Interface"
- column="other_config" key="bond-stable-id"/> if set. Otherwise,
- OpenFlow port number is used. Decisions are consistent across all
- <code>ovs-vswitchd</code> instances with equivalent
- <ref table="Interface" column="other_config" key="bond-stable-id"/>
- values.</p>
- </dd>
- </dl>
+ <column name="cfm_mpid">
+ <p>
+ A Maintenance Point ID (MPID) uniquely identifies each endpoint
+ within a Maintenance Association. The MPID is used to identify this
+ endpoint to other Maintenance Points in the MA. Each end of a link
+ being monitored should have a different MPID. Must be configured to
+ enable CFM on this <ref table="Interface"/>.
+ </p>
+ <p>
+ According to the 802.1ag specification, MPIDs can only range between
+ [1, 8191]. However, extended mode (see <ref column="other_config"
+ key="cfm_extended"/>) supports eight byte MPIDs.
+ </p>
+ </column>
- <p>These columns apply only to bonded ports. Their values are
- otherwise ignored.</p>
+ <column name="cfm_flap_count">
+ Counts the number of cfm fault flapps since boot. A flap is
+ considered to be a change of the <ref column="cfm_fault"/> value.
+ </column>
- <column name="bond_mode">
- <p>The type of bonding used for a bonded port. Defaults to
- <code>balance-slb</code> if unset.
+ <column name="cfm_fault">
+ <p>
+ Indicates a connectivity fault triggered by an inability to receive
+ heartbeats from any remote endpoint. When a fault is triggered on
+ <ref table="Interface"/>s participating in bonds, they will be
+ disabled.
+ </p>
+ <p>
+ Faults can be triggered for several reasons. Most importantly they
+ are triggered when no CCMs are received for a period of 3.5 times the
+ transmission interval. Faults are also triggered when any CCMs
+ indicate that a Remote Maintenance Point is not receiving CCMs but
+ able to send them. Finally, a fault is triggered if a CCM is
+ received which indicates unexpected configuration. Notably, this
+ case arises when a CCM is received which advertises the local MPID.
</p>
</column>
- <column name="bond_updelay">
- <p>For a bonded port, the number of milliseconds for which carrier must
- stay up on an interface before the interface is considered to be up.
- Specify <code>0</code> to enable the interface immediately.</p>
- <p>This setting is honored only when at least one bonded interface is
- already enabled. When no interfaces are enabled, then the first bond
- interface to come up is enabled immediately.</p>
+ <column name="cfm_fault_status" key="recv">
+ Indicates a CFM fault was triggered due to a lack of CCMs received on
+ the <ref table="Interface"/>.
</column>
- <column name="bond_downdelay">
- For a bonded port, the number of milliseconds for which carrier must
- stay down on an interface before the interface is considered to be
- down. Specify <code>0</code> to disable the interface immediately.
+ <column name="cfm_fault_status" key="rdi">
+ Indicates a CFM fault was triggered due to the reception of a CCM with
+ the RDI bit flagged. Endpoints set the RDI bit in their CCMs when they
+ are not receiving CCMs themselves. This typically indicates a
+ unidirectional connectivity failure.
</column>
- <column name="bond_fake_iface">
- For a bonded port, whether to create a fake internal interface with the
- name of the port. Use only for compatibility with legacy software that
- requires this.
+ <column name="cfm_fault_status" key="maid">
+ Indicates a CFM fault was triggered due to the reception of a CCM with
+ a MAID other than the one Open vSwitch uses. CFM broadcasts are tagged
+ with an identification number in addition to the MPID called the MAID.
+ Open vSwitch only supports receiving CCM broadcasts tagged with the
+ MAID it uses internally.
</column>
- <column name="lacp">
- <p>Configures LACP on this port. LACP allows directly connected
- switches to negotiate which links may be bonded. LACP may be enabled
- on non-bonded ports for the benefit of any switches they may be
- connected to. <code>active</code> ports are allowed to initiate LACP
- negotiations. <code>passive</code> ports are allowed to participate
- in LACP negotiations initiated by a remote switch, but not allowed to
- initiate such negotiations themselves. Defaults to <code>off</code>
- if unset. </p>
+ <column name="cfm_fault_status" key="loopback">
+ Indicates a CFM fault was triggered due to the reception of a CCM
+ advertising the same MPID configured in the <ref column="cfm_mpid"/>
+ column of this <ref table="Interface"/>. This may indicate a loop in
+ the network.
</column>
- </group>
+ <column name="cfm_fault_status" key="overflow">
+ Indicates a CFM fault was triggered because the CFM module received
+ CCMs from more remote endpoints than it can keep track of.
+ </column>
- <group title="Other Features">
- <column name="qos">
- Quality of Service configuration for this port.
+ <column name="cfm_fault_status" key="override">
+ Indicates a CFM fault was manually triggered by an administrator using
+ an <code>ovs-appctl</code> command.
</column>
- <column name="mac">
- The MAC address to use for this port for the purpose of choosing the
- bridge's MAC address. This column does not necessarily reflect the
- port's actual MAC address, nor will setting it change the port's actual
- MAC address.
+ <column name="cfm_fault_status" key="interval">
+ Indicates a CFM fault was triggered due to the reception of a CCM
+ frame having an invalid interval.
</column>
- <column name="fake_bridge">
- Does this port represent a sub-bridge for its tagged VLAN within the
- Bridge? See ovs-vsctl(8) for more information.
+ <column name="cfm_remote_opstate">
+ <p>When in extended mode, indicates the operational state of the
+ remote endpoint as either <code>up</code> or <code>down</code>. See
+ <ref column="other_config" key="cfm_opstate"/>.
+ </p>
</column>
- <column name="external_ids">
+ <column name="cfm_health">
<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.
+ Indicates the health of the interface as a percentage of CCM frames
+ received over 21 <ref column="other_config" key="cfm_interval"/>s.
+ The health of an interface is undefined if it is communicating with
+ more than one <ref column="cfm_remote_mpids"/>. It reduces if
+ healthy heartbeats are not received at the expected rate, and
+ gradually improves as healthy heartbeats are received at the desired
+ rate. Every 21 <ref column="other_config" key="cfm_interval"/>s, the
+ health of the interface is refreshed.
</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>.
+ As mentioned above, the faults can be triggered for several reasons.
+ The link health will deteriorate even if heartbeats are received but
+ they are reported to be unhealthy. An unhealthy heartbeat in this
+ context is a heartbeat for which either some fault is set or is out
+ of sequence. The interface health can be 100 only on receiving
+ healthy heartbeats at the desired rate.
</p>
</column>
- <column name="other_config">
- Key-value pairs for configuring rarely used port features. The
- currently defined key-value pairs are:
- <dl>
- <dt><code>bond-rebalance-interval</code></dt>
- <dd>For an SLB bonded port, the number of milliseconds between
- successive attempts to rebalance the bond, that is, to
- move source MACs and their flows from one interface on
- the bond to another in an attempt to keep usage of each
- interface roughly equal. The default is 10000 (10
- seconds), and the minimum is 1000 (1 second).</dd>
- <dt><code>bond-detect-mode</code></dt>
- <dd> Sets the method used to detect link failures in a bonded port.
- Options are <code>carrier</code> and <code>miimon</code>. Defaults
- to <code>carrier</code> which uses each interface's carrier to detect
- failures. When set to <code>miimon</code>, will check for failures
- by polling each interface's MII. </dd>
- <dt><code>bond-miimon-interval</code></dt>
- <dd> The number of milliseconds between successive attempts to
- poll each interface's MII. Only relevant on ports which use
- <code>miimon</code> to detect failures. </dd>
- <dt><code>bond-hash-basis</code></dt>
- <dd> An integer hashed along with flows when choosing output slaves.
- When changed, all flows will be assigned different hash values
- possibly causing slave selection decisions to change.</dd>
- <dt><code>lacp-system-id</code></dt>
- <dd> The LACP system ID of this <ref table="Port"/>. The system ID
- of a LACP bond is used to identify itself to its partners. Must
- be a nonzero MAC address.</dd>
- <dt><code>lacp-system-priority</code></dt>
- <dd> The LACP system priority of this <ref table="Port"/>. In
- LACP negotiations, link status decisions are made by the system
- with the numerically lower priority. Must be a number between 1
- and 65535.</dd>
- <dt><code>lacp-time</code></dt>
- <dd>
- <p>The LACP timing which should be used on this
- <ref table="Port"/>. Possible values are <code>fast</code>,
- <code>slow</code> and a positive number of milliseconds. By
- default <code>slow</code> is used. When configured to be
- <code>fast</code> LACP heartbeats are requested at a rate of once
- per second causing connectivity problems to be detected more
- quickly. In <code>slow</code> mode, heartbeats are requested at
- a rate of once every 30 seconds.</p>
-
- <p>Users may manually set a heartbeat transmission rate to increase
- the fault detection speed further. When manually set, OVS
- expects the partner switch to be configured with the same
- transmission rate. Manually setting <code>lacp-time</code> to
- something other than <code>fast</code> or <code>slow</code> is
- not supported by the LACP specification.</p>
- </dd>
- <dt><code>lacp-heartbeat</code></dt>
- <dd> Treats LACP like a simple heartbeat protocol for link state
- monitoring. Most features of the LACP protocol are disabled when
- this mode is in use.</dd>
- </dl>
+ <column name="cfm_remote_mpids">
+ When CFM is properly configured, Open vSwitch will occasionally
+ receive CCM broadcasts. These broadcasts contain the MPID of the
+ sending Maintenance Point. The list of MPIDs from which this
+ <ref table="Interface"/> is receiving broadcasts from is regularly
+ collected and written to this column.
</column>
- </group>
- </table>
- <table name="Interface" title="One physical network device in a Port.">
- An interface within a <ref table="Port"/>.
+ <column name="other_config" key="cfm_interval"
+ type='{"type": "integer"}'>
+ <p>
+ The interval, in milliseconds, between transmissions of CFM
+ heartbeats. Three missed heartbeat receptions indicate a
+ connectivity fault.
+ </p>
- <group title="Core Features">
- <column name="name">
- Interface name. Should be alphanumeric and no more than about 8 bytes
- long. May be the same as the port name, for non-bonded ports. Must
- otherwise be unique among the names of ports, interfaces, and bridges
- on a host.
+ <p>
+ In standard operation only intervals of 3, 10, 100, 1,000, 10,000,
+ 60,000, or 600,000 ms are supported. Other values will be rounded
+ down to the nearest value on the list. Extended mode (see <ref
+ column="other_config" key="cfm_extended"/>) supports any interval up
+ to 65,535 ms. In either mode, the default is 1000 ms.
+ </p>
+
+ <p>We do not recommend using intervals less than 100 ms.</p>
</column>
- <column name="mac">
- <p>Ethernet address to set for this interface. If unset then the
- default MAC address is used:</p>
- <ul>
- <li>For the local interface, the default is the lowest-numbered MAC
- address among the other bridge ports, either the value of the
- <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
- if set, or its actual MAC (for bonded ports, the MAC of its slave
- whose name is first in alphabetical order). Internal ports and
- bridge ports that are used as port mirroring destinations (see the
- <ref table="Mirror"/> table) are ignored.</li>
- <li>For other internal interfaces, the default MAC is randomly
- generated.</li>
- <li>External interfaces typically have a MAC address associated with
- their hardware.</li>
- </ul>
- <p>Some interfaces may not have a software-controllable MAC
- address.</p>
+ <column name="other_config" key="cfm_extended"
+ type='{"type": "boolean"}'>
+ When <code>true</code>, the CFM module operates in extended mode. This
+ causes it to use a nonstandard destination address to avoid conflicting
+ with compliant implementations which may be running concurrently on the
+ network. Furthermore, extended mode increases the accuracy of the
+ <code>cfm_interval</code> configuration parameter by breaking wire
+ compatibility with 802.1ag compliant implementations. And extended
+ mode allows eight byte MPIDs. Defaults to <code>false</code>.
+ </column>
+
+ <column name="other_config" key="cfm_demand" type='{"type": "boolean"}'>
+ <p>
+ When <code>true</code>, and
+ <ref column="other_config" key="cfm_extended"/> is true, the CFM
+ module operates in demand mode. When in demand mode, traffic
+ received on the <ref table="Interface"/> is used to indicate
+ liveness. CCMs are still transmitted and received. At least one
+ CCM must be received every 100 * <ref column="other_config"
+ key="cfm_interval"/> amount of time. Otherwise, even if traffic
+ are received, the CFM module will raise the connectivity fault.
+ </p>
+
+ <p>
+ Demand mode has a couple of caveats:
+ <ul>
+ <li>
+ To ensure that ovs-vswitchd has enough time to pull statistics
+ from the datapath, the fault detection interval is set to
+ 3.5 * MAX(<ref column="other_config" key="cfm_interval"/>, 500)
+ ms.
+ </li>
+
+ <li>
+ To avoid ambiguity, demand mode disables itself when there are
+ multiple remote maintenance points.
+ </li>
+
+ <li>
+ If the <ref table="Interface"/> is heavily congested, CCMs
+ containing the <ref column="other_config" key="cfm_opstate"/>
+ status may be dropped causing changes in the operational state to
+ be delayed. Similarly, if CCMs containing the RDI bit are not
+ received, unidirectional link failures may not be detected.
+ </li>
+ </ul>
+ </p>
+ </column>
+
+ <column name="other_config" key="cfm_opstate"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ When <code>down</code>, the CFM module marks all CCMs it generates as
+ operationally down without triggering a fault. This allows remote
+ maintenance points to choose not to forward traffic to the
+ <ref table="Interface"/> on which this CFM module is running.
+ Currently, in Open vSwitch, the opdown bit of CCMs affects
+ <ref table="Interface"/>s participating in bonds, and the bundle
+ OpenFlow action. This setting is ignored when CFM is not in extended
+ mode. Defaults to <code>up</code>.
</column>
- <column name="ofport">
- <p>OpenFlow port number for this interface. Unlike most columns, this
- column's value should be set only by Open vSwitch itself. Other
- clients should set this column to an empty set (the default) when
- creating an <ref table="Interface"/>.</p>
- <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 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>
+ <column name="other_config" key="cfm_ccm_vlan"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
+ When set, the CFM module will apply a VLAN tag to all CCMs it generates
+ with the given value. May be the string <code>random</code> in which
+ case each CCM will be tagged with a different randomly generated VLAN.
</column>
+
+ <column name="other_config" key="cfm_ccm_pcp"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 7}'>
+ When set, the CFM module will apply a VLAN tag to all CCMs it generates
+ with the given PCP value, the VLAN ID of the tag is governed by the
+ value of <ref column="other_config" key="cfm_ccm_vlan"/>. If
+ <ref column="other_config" key="cfm_ccm_vlan"/> is unset, a VLAN ID of
+ zero is used.
+ </column>
+
</group>
- <group title="System-Specific Details">
- <column name="type">
- The interface type, one of:
- <dl>
- <dt><code>system</code></dt>
- <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
- Sometimes referred to as ``external interfaces'' since they are
- generally connected to hardware external to that on which the Open
- vSwitch is running. The empty string is a synonym for
- <code>system</code>.</dd>
- <dt><code>internal</code></dt>
- <dd>A simulated network device that sends and receives traffic. An
- internal interface whose <ref column="name"/> is the same as its
- bridge's <ref table="Open_vSwitch" column="name"/> is called the
- ``local interface.'' It does not make sense to bond an internal
- interface, so the terms ``port'' and ``interface'' are often used
- imprecisely for internal interfaces.</dd>
- <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 2890 Generic Routing Encapsulation over IPv4
- tunnel. Each tunnel must be uniquely identified by the
- combination of <ref column="options" key="remote_ip"/>,
- <ref column="options" key="local_ip"/>, and
- <ref column="options" key="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. <ref column="options" key="in_key"/> is considered
- more specific than <ref column="options" key="local_ip"/> if a port
- 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>
- </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>in_key</code></dt>
- <dd>Optional. The GRE key that received packets must contain.
- It may either be a 32-bit number (no key and a key of 0 are
- treated as equivalent) or the word <code>flow</code>. If
- <code>flow</code> is specified then any key will be accepted
- and the key will be placed in the <code>tun_id</code> field
- for matching in the flow table. The ovs-ofctl manual page
- contains additional information about matching fields in
- OpenFlow flows. Default is no key.</dd>
- </dl>
- <dl>
- <dt><code>out_key</code></dt>
- <dd>Optional. The GRE key to be set on outgoing packets. It may
- 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 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>
- <dt><code>key</code></dt>
- <dd>Optional. Shorthand to set <code>in_key</code> and
- <code>out_key</code> at the same time.</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>csum</code></dt>
- <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>df_inherit</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be copied
- from the inner IP headers (those of the encapsulated traffic)
- to the outer (tunnel) headers. Default is disabled; set to
- <code>true</code> to enable.</dd>
- </dl>
- <dl>
- <dt><code>df_default</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be set by
- default on tunnel headers if the <code>df_inherit</code> option
- is not set, or if the encapsulated packet is not IP. Default
- is enabled; set to <code>false</code> to disable.</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.
- 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>ipsec_gre</code></dt>
- <dd>An Ethernet over RFC 2890 Generic Routing Encapsulation
- over IPv4 IPsec tunnel. Each tunnel (including those of type
- <code>gre</code>) must be uniquely identified by the
- combination of <ref column="options" key="remote_ip"/> and
- <ref column="options" key="local_ip"/>. 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.
- An authentication method of <ref column="options" key="peer_cert"/>
- or <ref column="options" key="psk"/> must be defined. 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>peer_cert</code></dt>
- <dd>Required for certificate authentication. A string
- containing the peer's certificate in PEM format.
- Additionally the host's certificate must be specified
- with the <code>certificate</code> option.</dd>
- </dl>
- <dl>
- <dt><code>certificate</code></dt>
- <dd>Required for certificate authentication. The name of a
- PEM file containing a certificate that will be presented
- to the peer during authentication.</dd>
- </dl>
- <dl>
- <dt><code>private_key</code></dt>
- <dd>Optional for certificate authentication. The name of
- a PEM file containing the private key associated with
- <code>certificate</code>. If <code>certificate</code>
- contains the private key, this option may be omitted.</dd>
- </dl>
- <dl>
- <dt><code>psk</code></dt>
- <dd>Required for pre-shared key authentication. Specifies a
- pre-shared key for authentication that must be identical on
- both sides of the tunnel.</dd>
- </dl>
- <dl>
- <dt><code>in_key</code></dt>
- <dd>Optional. The GRE key that received packets must contain.
- It may either be a 32-bit number (no key and a key of 0 are
- treated as equivalent) or the word <code>flow</code>. If
- <code>flow</code> is specified then any key will be accepted
- and the key will be placed in the <code>tun_id</code> field
- for matching in the flow table. The ovs-ofctl manual page
- contains additional information about matching fields in
- OpenFlow flows. Default is no key.</dd>
- </dl>
- <dl>
- <dt><code>out_key</code></dt>
- <dd>Optional. The GRE key to be set on outgoing packets. It may
- 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 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>
- <dt><code>key</code></dt>
- <dd>Optional. Shorthand to set <code>in_key</code> and
- <code>out_key</code> at the same time.</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>csum</code></dt>
- <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>df_inherit</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be copied
- from the inner IP headers (those of the encapsulated traffic)
- to the outer (tunnel) headers. Default is disabled; set to
- <code>true</code> to enable.</dd>
- </dl>
- <dl>
- <dt><code>df_default</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be set by
- default on tunnel headers if the <code>df_inherit</code> option
- is not set, or if the encapsulated packet is not IP. Default
- is enabled; set to <code>false</code> to disable.</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.
- 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>
- </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
- destination ports respectively. Each tunnel must be uniquely
- identified by the combination of
- <ref column="options" key="remote_ip"/> and
- <ref column="options" key="local_ip"/>. If two ports are defined
- that are the same except one includes
- <ref column="options" key="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 <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>df_inherit</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be copied
- from the inner IP headers (those of the encapsulated traffic)
- to the outer (tunnel) headers. Default is disabled; set to
- <code>true</code> to enable.</dd>
- </dl>
- <dl>
- <dt><code>df_default</code></dt>
- <dd>Optional. If enabled, the Don't Fragment bit will be set by
- default on tunnel headers if the <code>df_inherit</code> option
- is not set, or if the encapsulated packet is not IP. Default
- is enabled; set to <code>false</code> to disable.</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.
- 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>
- <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>
- <dt><code>null</code></dt>
- <dd>An ignored interface.</dd>
- </dl>
+ <group title="Bonding Configuration">
+ <column name="other_config" key="lacp-port-id"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port ID of this <ref table="Interface"/>. Port IDs are
+ used in LACP negotiations to identify individual ports
+ participating in a bond.
+ </column>
+
+ <column name="other_config" key="lacp-port-priority"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port priority of this <ref table="Interface"/>. In LACP
+ negotiations <ref table="Interface"/>s with numerically lower
+ priorities are preferred for aggregation.
</column>
- <column name="options">
- Configuration options whose interpretation varies based on
- <ref column="type"/>.
+ <column name="other_config" key="lacp-aggregation-key"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP aggregation key of this <ref table="Interface"/>. <ref
+ table="Interface"/>s with different aggregation keys may not be active
+ within a given <ref table="Port"/> at the same time.
</column>
</group>
- <group title="Interface Status">
+ <group title="Virtual Machine Identifiers">
<p>
- Status information about interfaces attached to bridges, updated every
- 5 seconds. Not all interfaces have all of these properties; virtual
- interfaces don't have a link speed, for example. Non-applicable
- columns will have empty values.
+ These key-value pairs specifically apply to an interface that
+ represents a virtual Ethernet interface connected to a virtual
+ machine. These key-value pairs should not be present for other types
+ of interfaces. Keys whose names end in <code>-uuid</code> have
+ values that uniquely identify the entity in question. For a Citrix
+ XenServer hypervisor, these values are UUIDs in RFC 4122 format.
+ Other hypervisors may use other formats.
</p>
- <column name="admin_state">
- <p>
- The administrative state of the physical network link.
- </p>
+
+ <column name="external_ids" key="attached-mac">
+ The MAC address programmed into the ``virtual hardware'' for this
+ interface, in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ For Citrix XenServer, this is the value of the <code>MAC</code> field
+ in the VIF record for this interface.
</column>
- <column name="link_state">
- <p>
- The observed state of the physical network link. This is ordinarily
- the link's carrier status. If the interface's <ref table="Port"/> is
- a bond configured for miimon monitoring, it is instead the network
- link's miimon status.
- </p>
+ <column name="external_ids" key="iface-id">
+ A system-unique identifier for the interface. On XenServer, this will
+ commonly be the same as <ref column="external_ids" key="xs-vif-uuid"/>.
</column>
- <column name="link_speed">
+ <column name="external_ids" key="iface-status"
+ type='{"type": "string",
+ "enum": ["set", ["active", "inactive"]]}'>
<p>
- The negotiated speed of the physical network link.
- Valid values are positive integers greater than 0.
+ Hypervisors may sometimes have more than one interface associated
+ with a given <ref column="external_ids" key="iface-id"/>, only one of
+ which is actually in use at a given time. For example, in some
+ circumstances XenServer has both a ``tap'' and a ``vif'' interface
+ for a single <ref column="external_ids" key="iface-id"/>, but only
+ uses one of them at a time. A hypervisor that behaves this way must
+ mark the currently in use interface <code>active</code> and the
+ others <code>inactive</code>. A hypervisor that never has more than
+ one interface for a given <ref column="external_ids" key="iface-id"/>
+ may mark that interface <code>active</code> or omit <ref
+ column="external_ids" key="iface-status"/> entirely.
</p>
- </column>
- <column name="duplex">
<p>
- The duplex mode of the physical network link.
+ During VM migration, a given <ref column="external_ids"
+ key="iface-id"/> might transiently be marked <code>active</code> on
+ two different hypervisors. That is, <code>active</code> means that
+ this <ref column="external_ids" key="iface-id"/> is the active
+ instance within a single hypervisor, not in a broader scope.
+ There is one exception: some hypervisors support ``migration'' from a
+ given hypervisor to itself (most often for test purposes). During
+ such a ``migration,'' two instances of a single <ref
+ column="external_ids" key="iface-id"/> might both be briefly marked
+ <code>active</code> on a single hypervisor.
</p>
</column>
- <column name="mtu">
+ <column name="external_ids" key="xs-vif-uuid">
+ The virtual interface associated with this interface.
+ </column>
+
+ <column name="external_ids" key="xs-network-uuid">
+ The virtual network to which this interface is attached.
+ </column>
+
+ <column name="external_ids" key="vm-id">
+ The VM to which this interface belongs. On XenServer, this will be the
+ same as <ref column="external_ids" key="xs-vm-uuid"/>.
+ </column>
+
+ <column name="external_ids" key="xs-vm-uuid">
+ The VM to which this interface belongs.
+ </column>
+ </group>
+
+ <group title="VLAN Splinters">
+ <p>
+ The ``VLAN splinters'' feature increases Open vSwitch compatibility
+ with buggy network drivers in old versions of Linux that do not
+ properly support VLANs when VLAN devices are not used, at some cost
+ in memory and performance.
+ </p>
+
+ <p>
+ When VLAN splinters are enabled on a particular interface, Open vSwitch
+ creates a VLAN device for each in-use VLAN. For sending traffic tagged
+ with a VLAN on the interface, it substitutes the VLAN device. Traffic
+ received on the VLAN device is treated as if it had been received on
+ the interface on the particular VLAN.
+ </p>
+
+ <p>
+ VLAN splinters consider a VLAN to be in use if:
+ </p>
+
+ <ul>
+ <li>
+ The VLAN is the <ref table="Port" column="tag"/> value in any <ref
+ table="Port"/> record.
+ </li>
+
+ <li>
+ The VLAN is listed within the <ref table="Port" column="trunks"/>
+ column of the <ref table="Port"/> record of an interface on which
+ VLAN splinters are enabled.
+
+ An empty <ref table="Port" column="trunks"/> does not influence the
+ in-use VLANs: creating 4,096 VLAN devices is impractical because it
+ will exceed the current 1,024 port per datapath limit.
+ </li>
+
+ <li>
+ An OpenFlow flow within any bridge matches the VLAN.
+ </li>
+ </ul>
+
+ <p>
+ The same set of in-use VLANs applies to every interface on which VLAN
+ splinters are enabled. That is, the set is not chosen separately for
+ each interface but selected once as the union of all in-use VLANs based
+ on the rules above.
+ </p>
+
+ <p>
+ It does not make sense to enable VLAN splinters on an interface for an
+ access port, or on an interface that is not a physical port.
+ </p>
+
+ <p>
+ VLAN splinters are deprecated. When broken device drivers are no
+ longer in widespread use, we will delete this feature.
+ </p>
+
+ <column name="other_config" key="enable-vlan-splinters"
+ type='{"type": "boolean"}'>
<p>
- The MTU (maximum transmission unit); i.e. the largest
- amount of data that can fit into a single Ethernet frame.
- The standard Ethernet MTU is 1500 bytes. Some physical media
- and many kinds of virtual interfaces can be configured with
- higher MTUs.
+ Set to <code>true</code> to enable VLAN splinters on this interface.
+ Defaults to <code>false</code>.
</p>
+
<p>
- This column will be empty for an interface that does not
- have an MTU as, for example, some kinds of tunnels do not.
+ VLAN splinters increase kernel and userspace memory overhead, so do
+ not use them unless they are needed.
</p>
- </column>
- <column name="status">
<p>
- Key-value pairs that report port status. Supported status values are
- <ref column="type"/>-dependent; some interfaces may not have a valid
- <ref column="status" key="driver_name"/>, for example.
+ VLAN splinters do not support 802.1p priority tags. Received
+ priorities will appear to be 0, regardless of their actual values,
+ and priorities on transmitted packets will also be cleared to 0.
</p>
- <p>The currently defined key-value pairs are:</p>
- <dl>
- <dt><code>driver_name</code></dt>
- <dd>The name of the device driver controlling the network
- adapter.</dd>
- </dl>
- <dl>
- <dt><code>driver_version</code></dt>
- <dd>The version string of the device driver controlling the
- network adapter.</dd>
- </dl>
- <dl>
- <dt><code>firmware_version</code></dt>
- <dd>The version string of the network adapter's firmware, if
- available.</dd>
- </dl>
- <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>.</dd>
- </dl>
- <dl>
- <dt><code>tunnel_egress_iface</code></dt>
- <dd>Egress interface for tunnels. Currently only relevant for GRE
- and CAPWAP tunnels. On Linux systems, this column will show
- the name of the interface which is responsible for routing
- traffic destined for the configured
- <ref column="options" key="remote_ip"/>. This could be an
- internal interface such as a bridge port.</dd>
- </dl>
- <dl>
- <dt><code>tunnel_egress_iface_carrier</code></dt>
- <dd>Whether a carrier is detected on
- <ref column="status" key="tunnel_egress_iface"/>. Valid values
- are <code>down</code> and <code>up</code>.</dd>
- </dl>
</column>
</group>
- <group title="Ingress Policing">
+ <group title="Auto Attach Configuration">
<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.
+ Auto Attach configuration for a particular interface.
</p>
+
+ <column name="lldp" key="enable" type='{"type": "boolean"}'>
+ True to enable LLDP on this <ref table="Interface"/>. If not
+ specified, LLDP will be disabled by default.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Flow_Table" title="OpenFlow table configuration">
+ <p>Configuration for a particular OpenFlow table.</p>
+
+ <column name="name">
+ The table's name. Set this column to change the name that controllers
+ will receive when they request table statistics, e.g. <code>ovs-ofctl
+ dump-tables</code>. The name does not affect switch behavior.
+ </column>
+
+ <group title="Eviction Policy">
<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).
+ Open vSwitch supports limiting the number of flows that may be
+ installed in a flow table, via the <ref column="flow_limit"/> column.
+ When adding a flow would exceed this limit, by default Open vSwitch
+ reports an error, but there are two ways to configure Open vSwitch to
+ instead delete (``evict'') a flow to make room for the new one:
</p>
+
+ <ul>
+ <li>
+ Set the <ref column="overflow_policy"/> column to <code>evict</code>.
+ </li>
+
+ <li>
+ Send an OpenFlow 1.4+ ``table mod request'' to enable eviction for
+ the flow table (e.g. <code>ovs-ofctl -O OpenFlow14 mod-table br0 0
+ evict</code> to enable eviction on flow table 0 of bridge
+ <code>br0</code>).
+ </li>
+ </ul>
+
<p>
- Policing is currently implemented only on Linux. The Linux
- implementation uses a simple ``token bucket'' approach:
+ When a flow must be evicted due to overflow, the flow to evict is
+ chosen through an approximation of the following algorithm. This
+ algorithm is used regardless of how eviction was enabled:
</p>
- <ul>
+
+ <ol>
<li>
- The size of the bucket corresponds to <ref
- column="ingress_policing_burst"/>. Initially the bucket is full.
+ Divide the flows in the table into groups based on the values of the
+ fields or subfields specified in the <ref column="groups"/> column,
+ so that all of the flows in a given group have the same values for
+ those fields. If a flow does not specify a given field, that field's
+ value is treated as 0. If <ref column="groups"/> is empty, then all
+ of the flows in the flow table are treated as a single group.
</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.
+ Consider the flows in the largest group, that is, the group that
+ contains the greatest number of flows. If two or more groups all
+ have the same largest number of flows, consider the flows in all of
+ those groups.
+ </li>
+
+ <li>
+ If the flows under consideration have different importance values,
+ eliminate from consideration any flows except those with the lowest
+ importance. (``Importance,'' a 16-bit integer value attached to each
+ flow, was introduced in OpenFlow 1.4. Flows inserted with older
+ versions of OpenFlow always have an importance of 0.)
</li>
+
<li>
- Whenever it is not full, the bucket is refilled with tokens at the
- rate specified by <ref column="ingress_policing_rate"/>.
+ Among the flows under consideration, choose the flow that expires
+ soonest for eviction.
</li>
- </ul>
+ </ol>
+
<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.
+ The eviction process only considers flows that have an idle timeout
+ or a hard timeout. That is, eviction never deletes permanent flows.
+ (Permanent flows do count against <ref column="flow_limit"/>.)
</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 name="flow_limit">
+ If set, limits the number of flows that may be added to the table.
+ Open vSwitch may limit the number of flows in a table for other
+ reasons, e.g. due to hardware limitations or for resource availability
+ or performance reasons.
</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>
+ <column name="overflow_policy">
<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.
+ Controls the switch's behavior when an OpenFlow flow table
+ modification request would add flows in excess of <ref
+ column="flow_limit"/>. The supported values are:
</p>
- </column>
- </group>
-
- <group title="Connectivity Fault Management">
- <p>
- 802.1ag Connectivity Fault Management (CFM) allows a group of
- Maintenance Points (MPs) called a Maintenance Association (MA) to
- detect connectivity problems with each other. MPs within a MA should
- have complete and exclusive interconnectivity. This is verified by
- occasionally broadcasting Continuity Check Messages (CCMs) at a
- configurable transmission interval.
- </p>
- <p>
- According to the 802.1ag specification, each Maintenance Point should
- be configured out-of-band with a list of Remote Maintenance Points it
- should have connectivity to. Open vSwitch differs from the
- specification in this area. It simply assumes the link is faulted if
- no Remote Maintenance Points are reachable, and considers it not
- faulted otherwise.
- </p>
+ <dl>
+ <dt><code>refuse</code></dt>
+ <dd>
+ Refuse to add the flow or flows. This is also the default policy
+ when <ref column="overflow_policy"/> is unset.
+ </dd>
- <column name="cfm_mpid">
- A Maintenance Point ID (MPID) uniquely identifies each endpoint within
- a Maintenance Association. The MPID is used to identify this endpoint
- to other Maintenance Points in the MA. Each end of a link being
- monitored should have a different MPID. Must be configured to enable
- CFM on this <ref table="Interface"/>.
+ <dt><code>evict</code></dt>
+ <dd>
+ Delete a flow chosen according to the algorithm described above.
+ </dd>
+ </dl>
</column>
- <column name="cfm_fault">
+ <column name="groups">
<p>
- Indicates a connectivity fault triggered by an inability to receive
- heartbeats from any remote endpoint. When a fault is triggered on
- <ref table="Interface"/>s participating in bonds, they will be
- disabled.
+ When <ref column="overflow_policy"/> is <code>evict</code>, this
+ controls how flows are chosen for eviction when the flow table would
+ otherwise exceed <ref column="flow_limit"/> flows. Its value is a
+ set of NXM fields or sub-fields, each of which takes one of the forms
+ <code><var>field</var>[]</code> or
+ <code><var>field</var>[<var>start</var>..<var>end</var>]</code>,
+ e.g. <code>NXM_OF_IN_PORT[]</code>. Please see
+ <code>nicira-ext.h</code> for a complete list of NXM field names.
</p>
+
<p>
- Faults can be triggered for several reasons. Most importantly they
- are triggered when no CCMs are received for a period of 3.5 times the
- transmission interval. Faults are also triggered when any CCMs
- indicate that a Remote Maintenance Point is not receiving CCMs but
- able to send them. Finally, a fault is triggered if a CCM is
- received which indicates unexpected configuration. Notably, this
- case arises when a CCM is received which advertises the local MPID.
+ Open vSwitch ignores any invalid or unknown field specifications.
+ </p>
+
+ <p>
+ When eviction is not enabled, via <ref column="overflow_policy"/> or
+ an OpenFlow 1.4+ ``table mod,'' this column has no effect.
</p>
</column>
</group>
- <group title="Other Features">
+ <group title="Classifier Optimization">
+ <column name="prefixes">
+ <p>
+ This string set specifies which fields should be used for
+ address prefix tracking. Prefix tracking allows the
+ classifier to skip rules with longer than necessary prefixes,
+ resulting in better wildcarding for datapath flows.
+ </p>
+ <p>
+ Prefix tracking may be beneficial when a flow table contains
+ matches on IP address fields with different prefix lengths.
+ For example, when a flow table contains IP address matches on
+ both full addresses and proper prefixes, the full address
+ matches will typically cause the datapath flow to un-wildcard
+ the whole address field (depending on flow entry priorities).
+ In this case each packet with a different address gets handed
+ to the userspace for flow processing and generates its own
+ datapath flow. With prefix tracking enabled for the address
+ field in question packets with addresses matching shorter
+ prefixes would generate datapath flows where the irrelevant
+ address bits are wildcarded, allowing the same datapath flow
+ to handle all the packets within the prefix in question. In
+ this case many userspace upcalls can be avoided and the
+ overall performance can be better.
+ </p>
+ <p>
+ This is a performance optimization only, so packets will
+ receive the same treatment with or without prefix tracking.
+ </p>
+ <p>
+ The supported fields are: <code>tun_id</code>,
+ <code>tun_src</code>, <code>tun_dst</code>,
+ <code>nw_src</code>, <code>nw_dst</code> (or aliases
+ <code>ip_src</code> and <code>ip_dst</code>),
+ <code>ipv6_src</code>, and <code>ipv6_dst</code>. (Using this
+ feature for <code>tun_id</code> would only make sense if the
+ tunnel IDs have prefix structure similar to IP addresses.)
+ </p>
- <column name="lacp_current">
- Boolean value indicating LACP status for this interface. If true, this
- interface has current LACP information about its LACP partner. This
- information may be used to monitor the health of interfaces in a LACP
- enabled port. This column will be empty if LACP is not enabled.
- </column>
+ <p>
+ By default, the <code>prefixes=ip_dst,ip_src</code> are used
+ on each flow table. This instructs the flow classifier to
+ track the IP destination and source addresses used by the
+ rules in this specific flow table.
+ </p>
- <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. 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
- <ref column="external_ids" key="xs-vif-uuid"/>.</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.
+ The keyword <code>none</code> is recognized as an explicit
+ override of the default values, causing no prefix fields to be
+ tracked.
+ </p>
+
+ <p>
+ To set the prefix fields, the flow table record needs to
+ exist:
</p>
- <p>The currently defined key-value pairs for XenServer are:</p>
- <dl>
- <dt><code>xs-vif-uuid</code></dt>
- <dd>The virtual interface associated with this interface.</dd>
- <dt><code>xs-network-uuid</code></dt>
- <dd>The virtual network to which this interface is attached.</dd>
- <dt><code>xs-vm-uuid</code></dt>
- <dd>The VM to which this interface belongs.</dd>
- </dl>
- </column>
- <column name="other_config">
- Key-value pairs for rarely used interface features.
<dl>
- <dt><code>cfm_interval</code></dt>
- <dd> The transmission interval of CFM heartbeats in milliseconds.
- Three missed heartbeat receptions indicate a connectivity fault.
- Defaults to 1000ms. </dd>
- <dt><code>bond-stable-id</code></dt>
- <dd> A positive integer using in <code>stable</code> bond mode to
- make slave selection decisions. Allocating
- <ref column="other_config" key="bond-stable-id"/> values
- consistently across interfaces participating in a bond will
- guarantee consistent slave selection decisions across
- <code>ovs-vswitchd</code> instances when using <code>stable</code>
- bonding mode.</dd>
- <dt><code>lacp-port-id</code></dt>
- <dd> The LACP port ID of this <ref table="Interface"/>. Port IDs are
- used in LACP negotiations to identify individual ports
- participating in a bond. Must be a number between 1 and
- 65535.</dd>
- <dt><code>lacp-port-priority</code></dt>
- <dd> The LACP port priority of this <ref table="Interface"/>. In
- LACP negotiations <ref table="Interface"/>s with numerically lower
- priorities are preferred for aggregation. Must be a number between
- 1 and 65535.</dd>
- <dt><code>lacp-aggregation-key</code></dt>
- <dd> The LACP aggregation key of this <ref table="Interface"/>.
- <ref table="Interface"/>s with different aggregation keys may not
- be active within a given <ref table="Port"/> at the same time. Must
- be a number between 1 and 65535.</dd>
+ <dt><code>ovs-vsctl set Bridge br0 flow_tables:0=@N1 -- --id=@N1 create Flow_Table name=table0</code></dt>
+ <dd>
+ Creates a flow table record for the OpenFlow table number 0.
+ </dd>
+
+ <dt><code>ovs-vsctl set Flow_Table table0 prefixes=ip_dst,ip_src</code></dt>
+ <dd>
+ Enables prefix tracking for IP source and destination
+ address fields.
+ </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>
+ There is a maximum number of fields that can be enabled for any
+ one flow table. Currently this limit is 3.
+ </p>
</column>
</group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
</table>
<table name="QoS" title="Quality of Service configuration">
<p>Quality of Service (QoS) configuration for each Port that
- references it.</p>
+ references it.</p>
<column name="type">
- <p>The type of QoS to implement. The <ref table="Open_vSwitch"
- column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
- identifies the types that a switch actually supports. The currently
- defined types are listed below:</p>
+ <p>The type of QoS to implement. The currently defined types are
+ listed below:</p>
<dl>
<dt><code>linux-htb</code></dt>
<dd>
information on how this classifier works.
</dd>
</dl>
+ <dl>
+ <dt><code>linux-sfq</code></dt>
+ <dd>
+ Linux ``Stochastic Fairness Queueing'' classifier. See
+ <code>tc-sfq</code>(8) (also at
+ <code>http://linux.die.net/man/8/tc-sfq</code>) for information on
+ how this classifier works.
+ </dd>
+ </dl>
+ <dl>
+ <dt><code>linux-codel</code></dt>
+ <dd>
+ Linux ``Controlled Delay'' classifier. See <code>tc-codel</code>(8)
+ (also at
+ <code>http://man7.org/linux/man-pages/man8/tc-codel.8.html</code>)
+ for information on how this classifier works.
+ </dd>
+ </dl>
+ <dl>
+ <dt><code>linux-fq_codel</code></dt>
+ <dd>
+ Linux ``Fair Queuing with Controlled Delay'' classifier. See
+ <code>tc-fq_codel</code>(8) (also at
+ <code>http://man7.org/linux/man-pages/man8/tc-fq_codel.8.html</code>)
+ for information on how this classifier works.
+ </dd>
+ </dl>
</column>
<column name="queues">
<p>A map from queue numbers to <ref table="Queue"/> records. The
- supported range of queue numbers depend on <ref column="type"/>. The
- queue numbers are the same as the <code>queue_id</code> used in
- OpenFlow in <code>struct ofp_action_enqueue</code> and other
- structures. Queue 0 is used by OpenFlow output actions that do not
- specify a specific queue.</p>
- </column>
+ supported range of queue numbers depend on <ref column="type"/>. The
+ queue numbers are the same as the <code>queue_id</code> used in
+ OpenFlow in <code>struct ofp_action_enqueue</code> and other
+ structures.</p>
- <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> 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.
- Optional. If not specified, for physical interfaces, the
- default is the link rate. For other interfaces or if the
- link rate cannot be determined, the default is currently 100
- Mbps.</dd>
- </dl>
+ <p>
+ Queue 0 is the ``default queue.'' It is used by OpenFlow output
+ actions when no specific queue has been set. When no configuration for
+ queue 0 is present, it is automatically configured as if a <ref
+ table="Queue"/> record with empty <ref table="Queue" column="dscp"/>
+ and <ref table="Queue" column="other_config"/> columns had been
+ specified.
+ (Before version 1.6, Open vSwitch would leave queue 0 unconfigured in
+ this case. With some queuing disciplines, this dropped all packets
+ destined for the default queue.)
+ </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>
+ <group title="Configuration for linux-htb and linux-hfsc">
+ <p>
+ The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
+ the following key-value pair:
+ </p>
+
+ <column name="other_config" key="max-rate" type='{"type": "integer"}'>
+ Maximum rate shared by all queued traffic, in bit/s. Optional. If not
+ specified, for physical interfaces, the default is the link rate. For
+ other interfaces or if the link rate cannot be determined, the default
+ is currently 100 Mbps.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
</table>
<table name="Queue" title="QoS output queue.">
<p>A configuration for a port output queue, used in configuring Quality of
- Service (QoS) features. May be referenced by <ref column="queues"
- table="QoS"/> column in <ref table="QoS"/> table.</p>
-
- <column name="other_config">
- <p>Key-value pairs for configuring the output queue. The supported
- key-value pairs and their meanings depend on the <ref column="type"/>
- of the <ref column="QoS"/> records that reference this row.</p>
- <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
- column="type"/> of <code>min-rate</code> are:</p>
- <dl>
- <dt><code>min-rate</code></dt>
- <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>
- <dl>
- <dt><code>min-rate</code></dt>
- <dd>Minimum guaranteed bandwidth, in bit/s.</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>
- <dt><code>burst</code></dt>
- <dd>Burst size, in bits. This is the maximum amount of ``credits''
- that a queue can accumulate while it is idle. Optional. Details of
- the <code>linux-htb</code> implementation require a minimum burst
- size, so a too-small <code>burst</code> will be silently
- ignored.</dd>
- <dt><code>priority</code></dt>
- <dd>A nonnegative 32-bit integer. Defaults to 0 if
- unspecified. A queue with a smaller <code>priority</code>
- will receive all the excess bandwidth that it can use before
- a queue with a larger value receives any. Specific priority
- values are unimportant; only relative ordering matters.</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.</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>
+ Service (QoS) features. May be referenced by <ref column="queues"
+ table="QoS"/> column in <ref table="QoS"/> table.</p>
+
+ <column name="dscp">
+ If set, Open vSwitch will mark all traffic egressing this
+ <ref table="Queue"/> with the given DSCP bits. Traffic egressing the
+ default <ref table="Queue"/> is only marked if it was explicitly selected
+ as the <ref table="Queue"/> at the time the packet was output. If unset,
+ the DSCP bits of traffic egressing this <ref table="Queue"/> will remain
+ unchanged.
</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>
+ <group title="Configuration for linux-htb QoS">
+ <p>
+ <ref table="QoS"/> <ref table="QoS" column="type"/>
+ <code>linux-htb</code> may use <code>queue_id</code>s less than 61440.
+ It has the following key-value pairs defined.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even
+ if excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </column>
+
+ <column name="other_config" key="burst"
+ type='{"type": "integer", "minInteger": 1}'>
+ Burst size, in bits. This is the maximum amount of ``credits'' that a
+ queue can accumulate while it is idle. Optional. Details of the
+ <code>linux-htb</code> implementation require a minimum burst size, so
+ a too-small <code>burst</code> will be silently ignored.
+ </column>
+
+ <column name="other_config" key="priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
+ A queue with a smaller <code>priority</code> will receive all the
+ excess bandwidth that it can use before a queue with a larger value
+ receives any. Specific priority values are unimportant; only relative
+ ordering matters. Defaults to 0 if unspecified.
+ </column>
+ </group>
+
+ <group title="Configuration for linux-hfsc QoS">
+ <p>
+ <ref table="QoS"/> <ref table="QoS" column="type"/>
+ <code>linux-hfsc</code> may use <code>queue_id</code>s less than 61440.
+ It has the following key-value pairs defined.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even if
+ excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
</table>
- <table name="Mirror" title="Port mirroring (SPAN/RSPAN/ERSPAN).">
+ <table name="Mirror" title="Port mirroring.">
<p>A port mirror within a <ref table="Bridge"/>.</p>
<p>A port mirror configures a bridge to send selected frames to special
``mirrored'' ports, in addition to their normal destinations. Mirroring
- traffic may also be referred to as SPAN, RSPAN, or ERSPAN, depending on how
+ traffic may also be referred to as SPAN or RSPAN, depending on how
the mirrored traffic is sent.</p>
+ <p>
+ When a packet enters an Open vSwitch bridge, it becomes eligible for
+ mirroring based on its ingress port and VLAN. As the packet travels
+ through the flow tables, each time it is output to a port, it becomes
+ eligible for mirroring based on the egress port and VLAN. In Open
+ vSwitch 2.5 and later, mirroring occurs just after a packet first becomes
+ eligible, using the packet as it exists at that point; in Open vSwitch
+ 2.4 and earlier, mirroring occurs only after a packet has traversed all
+ the flow tables, using the original packet as it entered the bridge.
+ This makes a difference only when the flow table modifies the packet: in
+ Open vSwitch 2.4, the modifications are never visible to mirrors, whereas
+ in Open vSwitch 2.5 and later modifications made before the first output
+ that makes it eligible for mirroring to a particular destination are
+ visible.
+ </p>
+
+ <p>
+ A packet that enters an Open vSwitch bridge is mirrored to a particular
+ destination only once, even if it is eligible for multiple reasons. For
+ example, a packet would be mirrored to a particular <ref
+ column="output_port"/> only once, even if it is selected for mirroring to
+ that port by <ref column="select_dst_port"/> and <ref
+ column="select_src_port"/> in the same or different <ref table="Mirror"/>
+ records.
+ </p>
+
<column name="name">
Arbitrary identifier for the <ref table="Mirror"/>.
</column>
<p>Output port for selected packets, if nonempty.</p>
<p>Specifying a port for mirror output reserves that port exclusively
for mirroring. No frames other than those selected for mirroring
+ via this column
will be forwarded to the port, and any frames received on the port
will be discarded.</p>
<p>
The output port may be any kind of port supported by Open vSwitch.
- It may be, for example, a physical port (sometimes called SPAN), or a
- GRE tunnel (sometimes called ERSPAN).
+ It may be, for example, a physical port (sometimes called SPAN) or a
+ GRE tunnel.
</p>
</column>
<column name="output_vlan">
<p>Output VLAN for selected packets, if nonempty.</p>
<p>The frames will be sent out all ports that trunk
- <ref column="output_vlan"/>, as well as any ports with implicit VLAN
- <ref column="output_vlan"/>. When a mirrored frame is sent out a
- trunk port, the frame's VLAN tag will be set to
- <ref column="output_vlan"/>, replacing any existing tag; when it is
- sent out an implicit VLAN port, the frame will not be tagged. This
- type of mirroring is sometimes called RSPAN.</p>
+ <ref column="output_vlan"/>, as well as any ports with implicit VLAN
+ <ref column="output_vlan"/>. When a mirrored frame is sent out a
+ trunk port, the frame's VLAN tag will be set to
+ <ref column="output_vlan"/>, replacing any existing tag; when it is
+ sent out an implicit VLAN port, the frame will not be tagged. This
+ type of mirroring is sometimes called RSPAN.</p>
<p>
- The following destination MAC addresses will not be mirrored to a
- VLAN to avoid confusing switches that interpret the protocols that
- they represent:
+ See the documentation for
+ <ref column="other_config" key="forward-bpdu"/> in the
+ <ref table="Interface"/> table for a list of destination MAC
+ addresses which will not be mirrored to a VLAN to avoid confusing
+ switches that interpret the protocols that they represent.
</p>
- <dl>
- <dt><code>01:80:c2:00:00:00</code></dt>
- <dd>IEEE 802.1D Spanning Tree Protocol (STP).</dd>
-
- <dt><code>01:80:c2:00:00:01</code></dt>
- <dd>IEEE Pause frame.</dd>
-
- <dt><code>01:80:c2:00:00:0<var>x</var></code></dt>
- <dd>Other reserved protocols.</dd>
-
- <dt><code>01:00:0c:cc:cc:cc</code></dt>
- <dd>
- Cisco Discovery Protocol (CDP), VLAN Trunking Protocol (VTP),
- Dynamic Trunking Protocol (DTP), Port Aggregation Protocol (PAgP),
- and others.
- </dd>
-
- <dt><code>01:00:0c:cc:cc:cd</code></dt>
- <dd>Cisco Shared Spanning Tree Protocol PVSTP+.</dd>
-
- <dt><code>01:00:0c:cd:cd:cd</code></dt>
- <dd>Cisco STP Uplink Fast.</dd>
-
- <dt><code>01:00:0c:00:00:00</code></dt>
- <dd>Cisco Inter Switch Link.</dd>
- </dl>
<p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
- contains unmanaged switches. Consider an unmanaged physical switch
- with two ports: port 1, connected to an end host, and port 2,
- connected to an Open vSwitch configured to mirror received packets
- into VLAN 123 on port 2. Suppose that the end host sends a packet on
- port 1 that the physical switch forwards to port 2. The Open vSwitch
- forwards this packet to its destination and then reflects it back on
- port 2 in VLAN 123. This reflected packet causes the unmanaged
- physical switch to replace the MAC learning table entry, which
- correctly pointed to port 1, with one that incorrectly points to port
- 2. Afterward, the physical switch will direct packets destined for
- the end host to the Open vSwitch on port 2, instead of to the end
- host on port 1, disrupting connectivity. If mirroring to a VLAN is
- desired in this scenario, then the physical switch must be replaced
- by one that learns Ethernet addresses on a per-VLAN basis. In
- addition, learning should be disabled on the VLAN containing mirrored
- traffic. If this is not done then intermediate switches will learn
- the MAC address of each end host from the mirrored traffic. If
- packets being sent to that end host are also mirrored, then they will
- be dropped since the switch will attempt to send them out the input
- port. Disabling learning for the VLAN will cause the switch to
- correctly send the packet out all ports configured for that VLAN. If
- Open vSwitch is being used as an intermediate switch, learning can be
- disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
- in the appropriate <ref table="Bridge"/> table or tables.</p>
- Mirroring to a GRE tunnel has fewer caveats than mirroring to a
- VLAN and should generally be preferred.
- </p>
+ contains unmanaged switches. Consider an unmanaged physical switch
+ with two ports: port 1, connected to an end host, and port 2,
+ connected to an Open vSwitch configured to mirror received packets
+ into VLAN 123 on port 2. Suppose that the end host sends a packet on
+ port 1 that the physical switch forwards to port 2. The Open vSwitch
+ forwards this packet to its destination and then reflects it back on
+ port 2 in VLAN 123. This reflected packet causes the unmanaged
+ physical switch to replace the MAC learning table entry, which
+ correctly pointed to port 1, with one that incorrectly points to port
+ 2. Afterward, the physical switch will direct packets destined for
+ the end host to the Open vSwitch on port 2, instead of to the end
+ host on port 1, disrupting connectivity. If mirroring to a VLAN is
+ desired in this scenario, then the physical switch must be replaced
+ by one that learns Ethernet addresses on a per-VLAN basis. In
+ addition, learning should be disabled on the VLAN containing mirrored
+ traffic. If this is not done then intermediate switches will learn
+ the MAC address of each end host from the mirrored traffic. If
+ packets being sent to that end host are also mirrored, then they will
+ be dropped since the switch will attempt to send them out the input
+ port. Disabling learning for the VLAN will cause the switch to
+ correctly send the packet out all ports configured for that VLAN. If
+ Open vSwitch is being used as an intermediate switch, learning can be
+ disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
+ in the appropriate <ref table="Bridge"/> table or tables.</p>
+ <p>
+ Mirroring to a GRE tunnel has fewer caveats than mirroring to a
+ VLAN and should generally be preferred.
+ </p>
</column>
</group>
- <group title="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.
+ <group title="Statistics: Mirror counters">
+ <p>
+ Key-value pairs that report mirror statistics. The update period
+ is controlled by <ref column="other_config"
+ key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
+ </p>
+ <column name="statistics" key="tx_packets">
+ Number of packets transmitted through this mirror.
</column>
+ <column name="statistics" key="tx_bytes">
+ Number of bytes transmitted through this mirror.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
</group>
</table>
<dl>
<dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
<dd>
- <p>The specified SSL <var>port</var> (default: 6633) on the host at
- the given <var>ip</var>, which must be expressed as an IP address
- (not a DNS name). The <ref table="Open_vSwitch" column="ssl"/>
- column in the <ref table="Open_vSwitch"/> table must point to a
- valid SSL configuration when this form is used.</p>
+ <p>The specified SSL <var>port</var> 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>If <var>port</var> is not specified, it defaults to 6653.</p>
<p>SSL support is an optional feature that is not always built as
- part of Open vSwitch.</p>
+ 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: 6633) on the host at
- the given <var>ip</var>, which must be expressed as an IP address
- (not a DNS name).</dd>
+ <dd>
+ <p>
+ The specified TCP <var>port</var> on the host at the given
+ <var>ip</var>, which must be expressed as an IP address (not a
+ DNS name), where <var>ip</var> can be IPv4 or IPv6 address. If
+ <var>ip</var> is an IPv6 address, wrap it in square brackets,
+ e.g. <code>tcp:[::1]:6653</code>.
+ </p>
+ <p>
+ If <var>port</var> is not specified, it defaults to 6653.
+ </p>
+ </dd>
</dl>
<p>
The following connection methods are currently supported for service
<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.
+ Listens for SSL connections on the specified TCP <var>port</var>.
+ 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 (either IPv4 or IPv6). If
+ <var>ip</var> is an IPv6 address, wrap it in square brackets,
+ e.g. <code>pssl:6653:[::1]</code>.
</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.
+ If <var>port</var> is not specified, it defaults to
+ 6653. If <var>ip</var> is not specified then it listens only on
+ IPv4 (but not IPv6) addresses. 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>
+ If <var>port</var> is not specified, it currently to 6653.
+ </p>
+ <p>
+ SSL support is an optional feature that is not always built as
+ part of Open vSwitch.
</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.
+ <p>
+ Listens for connections on the specified TCP <var>port</var>. 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 (either IPv4 or IPv6). If
+ <var>ip</var> is an IPv6 address, wrap it in square brackets,
+ e.g. <code>ptcp:6653:[::1]</code>. If <var>ip</var> is not
+ specified then it listens only on IPv4 addresses.
+ </p>
+ <p>
+ If <var>port</var> is not specified, it defaults to 6653.
+ </p>
</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>
+ <ref column="target"/> values must be unique. Duplicate
+ <ref column="target"/> values yield unspecified results.</p>
</column>
<column name="connection_mode">
<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>
+ 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.
+ 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>
Default is implementation-specific. A value of 0 disables
inactivity probes.
</column>
- </group>
+ </group>
+
+ <group title="Asynchronous Messages">
+ <p>
+ OpenFlow switches send certain messages to controllers spontanenously,
+ that is, not in response to any request from the controller. These
+ messages are called ``asynchronous messages.'' These columns allow
+ asynchronous messages to be limited or disabled to ensure the best use
+ of network resources.
+ </p>
+
+ <column name="enable_async_messages">
+ The OpenFlow protocol enables asynchronous messages at time of
+ connection establishment, which means that a controller can receive
+ asynchronous messages, potentially many of them, even if it turns them
+ off immediately after connecting. Set this column to
+ <code>false</code> to change Open vSwitch behavior to disable, by
+ default, all asynchronous messages. The controller can use the
+ <code>NXT_SET_ASYNC_CONFIG</code> Nicira extension to OpenFlow to turn
+ on any messages that it does want to receive, if any.
+ </column>
+
+ <group title="Controller Rate Limiting">
+ <p>
+ A switch can forward packets to a controller over the OpenFlow
+ protocol. Forwarding packets this way at too high a rate can
+ overwhelm a controller, frustrate use of the OpenFlow connection for
+ other purposes, increase the latency of flow setup, and use an
+ unreasonable amount of bandwidth. Therefore, Open vSwitch supports
+ limiting the rate of packet forwarding to a controller.
+ </p>
+
+ <p>
+ There are two main reasons in OpenFlow for a packet to be sent to a
+ controller: either the packet ``misses'' in the flow table, that is,
+ there is no matching flow, or a flow table action says to send the
+ packet to the controller. Open vSwitch limits the rate of each kind
+ of packet separately at the configured rate. Therefore, the actual
+ rate that packets are sent to the controller can be up to twice the
+ configured rate, when packets are sent for both reasons.
+ </p>
+
+ <p>
+ This feature is specific to forwarding packets over an OpenFlow
+ connection. It is not general-purpose QoS. See the <ref
+ table="QoS"/> table for quality of service configuration, and <ref
+ column="ingress_policing_rate" table="Interface"/> in the <ref
+ table="Interface"/> table for ingress policing configuration.
+ </p>
- <group title="OpenFlow Rate Limiting">
<column name="controller_rate_limit">
- <p>The maximum rate at which packets in unknown flows will be
- forwarded to the OpenFlow controller, in packets per second. This
- feature prevents a single bridge from overwhelming the controller.
- If not specified, the default is implementation-specific.</p>
- <p>In addition, when a high rate triggers rate-limiting, Open
- vSwitch queues controller packets for each port and transmits
- them to the controller at the configured rate. The number of
- queued packets is limited by
- the <ref column="controller_burst_limit"/> value. The packet
- queue is shared fairly among the ports on a bridge.</p><p>Open
- vSwitch maintains two such packet rate-limiters per bridge.
- One of these applies to packets sent up to the controller
- because they do not correspond to any flow. The other applies
- to packets sent up to the controller by request through flow
- actions. When both rate-limiters are filled with packets, the
- actual rate that packets are sent to the controller is up to
- twice the specified rate.</p>
+ <p>
+ The maximum rate at which the switch will forward packets to the
+ OpenFlow controller, in packets per second. If no value is
+ specified, rate limiting is disabled.
+ </p>
</column>
<column name="controller_burst_limit">
- In conjunction with <ref column="controller_rate_limit"/>,
- the maximum number of unused packet credits that the bridge will
- allow to accumulate, in packets. If not specified, the default
- is implementation-specific.
+ <p>
+ When a high rate triggers rate-limiting, Open vSwitch queues
+ packets to the controller for each port and transmits them to the
+ controller at the configured rate. This value limits the number of
+ queued packets. Ports on a bridge share the packet queue fairly.
+ </p>
+
+ <p>
+ This value has no effect unless <ref
+ column="controller_rate_limit"/> is configured. The current
+ default when this value is not specified is one-quarter of <ref
+ column="controller_rate_limit"/>, meaning that queuing can delay
+ forwarding a packet to the controller by up to 250 ms.
+ </p>
</column>
+
+ <group title="Controller Rate Limiting Statistics">
+ <p>
+ These values report the effects of rate limiting. Their values are
+ relative to establishment of the most recent OpenFlow connection,
+ or since rate limiting was enabled, whichever happened more
+ recently. Each consists of two values, one with <code>TYPE</code>
+ replaced by <code>miss</code> for rate limiting flow table misses,
+ and the other with <code>TYPE</code> replaced by
+ <code>action</code> for rate limiting packets sent by OpenFlow
+ actions.
+ </p>
+
+ <p>
+ These statistics are reported only when controller rate limiting is
+ enabled.
+ </p>
+
+ <column name="status" key="packet-in-TYPE-bypassed"
+ type='{"type": "integer", "minInteger": 0}'>
+ Number of packets sent directly to the controller, without queuing,
+ because the rate did not exceed the configured maximum.
+ </column>
+
+ <column name="status" key="packet-in-TYPE-queued"
+ type='{"type": "integer", "minInteger": 0}'>
+ Number of packets added to the queue to send later.
+ </column>
+
+ <column name="status" key="packet-in-TYPE-dropped"
+ type='{"type": "integer", "minInteger": 0}'>
+ Number of packets added to the queue that were later dropped due to
+ overflow. This value is less than or equal to <ref column="status"
+ key="packet-in-TYPE-queued"/>.
+ </column>
+
+ <column name="status" key="packet-in-TYPE-backlog"
+ type='{"type": "integer", "minInteger": 0}'>
+ Number of packets currently queued. The other statistics increase
+ monotonically, but this one fluctuates between 0 and the <ref
+ column="controller_burst_limit"/> as conditions change.
+ </column>
+ </group>
+ </group>
</group>
<group title="Additional In-Band Configuration">
<p>These values are considered only in in-band control mode (see
- <ref column="connection_mode"/>).</p>
+ <ref column="connection_mode"/>).</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,
</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>
-
<group title="Controller Status">
<column name="is_connected">
<code>true</code> if currently connected to this controller,
<code>false</code> otherwise.
</column>
- <column name="role">
+ <column name="role"
+ type='{"type": "string", "enum": ["set", ["other", "master", "slave"]]}'>
<p>The level of authority this controller has on the associated
- bridge. Possible values are:</p>
+ bridge. Possible values are:</p>
<dl>
<dt><code>other</code></dt>
<dd>Allows the controller access to all OpenFlow features.</dd>
<dt><code>master</code></dt>
<dd>Equivalent to <code>other</code>, except that there may be at
- most one master controller at a time. When a controller configures
- itself as <code>master</code>, any existing master is demoted to
- the <code>slave</code>role.</dd>
+ most one master controller at a time. When a controller configures
+ itself as <code>master</code>, any existing master is demoted to
+ the <code>slave</code> role.</dd>
<dt><code>slave</code></dt>
<dd>Allows the controller read-only access to OpenFlow features.
- Attempts to modify the flow table will be rejected with an
- error. Slave controllers do not receive OFPT_PACKET_IN or
- OFPT_FLOW_REMOVED messages, but they do receive OFPT_PORT_STATUS
- messages.</dd>
+ Attempts to modify the flow table will be rejected with an
+ error. Slave controllers do not receive OFPT_PACKET_IN or
+ OFPT_FLOW_REMOVED messages, but they do receive OFPT_PORT_STATUS
+ messages.</dd>
</dl>
</column>
- <column name="status">
- <p>Key-value pairs that report controller status.</p>
+ <column name="status" key="last_error">
+ A human-readable description of the last error on the connection
+ to the controller; i.e. <code>strerror(errno)</code>. This key
+ will exist only if an error has occurred.
+ </column>
+
+ <column name="status" key="state"
+ type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
+ <p>
+ The state of the connection to the controller:
+ </p>
<dl>
- <dt><code>last_error</code></dt>
- <dd>A human-readable description of the last error on the connection
- to the controller; i.e. <code>strerror(errno)</code>. This key
- will exist only if an error has occurred.</dd>
- <dt><code>state</code></dt>
- <dd>The state of the connection to the controller. Possible values
- are: <code>VOID</code> (connection is disabled),
- <code>BACKOFF</code> (attempting to reconnect at an increasing
- period), <code>CONNECTING</code> (attempting to connect),
- <code>ACTIVE</code> (connected, remote host responsive), and
- <code>IDLE</code> (remote host idle, sending keep-alive). These
- values may change in the future. They are provided only for human
- consumption.</dd>
- <dt><code>sec_since_connect</code></dt>
- <dd>The amount of time since this controller last successfully
- connected to the switch (in seconds). Value is empty if controller
- has never successfully connected.</dd>
- <dt><code>sec_since_disconnect</code></dt>
- <dd>The amount of time since this controller last disconnected from
- the switch (in seconds). Value is empty if controller has never
- disconnected.</dd>
+ <dt><code>VOID</code></dt>
+ <dd>Connection is disabled.</dd>
+
+ <dt><code>BACKOFF</code></dt>
+ <dd>Attempting to reconnect at an increasing period.</dd>
+
+ <dt><code>CONNECTING</code></dt>
+ <dd>Attempting to connect.</dd>
+
+ <dt><code>ACTIVE</code></dt>
+ <dd>Connected, remote host responsive.</dd>
+
+ <dt><code>IDLE</code></dt>
+ <dd>Connection is idle. Waiting for response to keep-alive.</dd>
</dl>
+ <p>
+ These values may change in the future. They are provided only for
+ human consumption.
+ </p>
+ </column>
+
+ <column name="status" key="sec_since_connect"
+ type='{"type": "integer", "minInteger": 0}'>
+ The amount of time since this controller last successfully connected to
+ the switch (in seconds). Value is empty if controller has never
+ successfully connected.
+ </column>
+
+ <column name="status" key="sec_since_disconnect"
+ type='{"type": "integer", "minInteger": 1}'>
+ The amount of time since this controller last disconnected from
+ the switch (in seconds). Value is empty if controller has never
+ disconnected.
+ </column>
+ </group>
+
+ <group title="Connection Parameters">
+ <p>
+ Additional configuration for a connection between the controller
+ and the Open vSwitch.
+ </p>
+
+ <column name="other_config" key="dscp"
+ type='{"type": "integer"}'>
+ The Differentiated Service Code Point (DSCP) is specified using 6 bits
+ in the Type of Service (TOS) field in the IP header. DSCP provides a
+ mechanism to classify the network traffic and provide Quality of
+ Service (QoS) on IP networks.
+
+ The DSCP value specified here is used when establishing the connection
+ between the controller and the Open vSwitch. If no value is specified,
+ a default value of 48 is chosen. Valid DSCP values must be in the
+ range 0 to 63.
</column>
</group>
+
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ <column name="other_config"/>
+ </group>
</table>
<table name="Manager" title="OVSDB management connection.">
<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.
+ The specified SSL <var>port</var> 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.
+ If <var>port</var> is not specified, it defaults to 6640.
+ </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).
+ <p>
+ The specified TCP <var>port</var> on the host at the given
+ <var>ip</var>, which must be expressed as an IP address (not a
+ DNS name), where <var>ip</var> can be IPv4 or IPv6 address. If
+ <var>ip</var> is an IPv6 address, wrap it in square brackets,
+ e.g. <code>tcp:[::1]:6640</code>.
+ </p>
+ <p>
+ If <var>port</var> is not specified, it defaults to 6640.
+ </p>
</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>
+ Listens for SSL connections on the specified TCP <var>port</var>.
+ Specify 0 for <var>port</var> to have the kernel automatically
+ choose an available port. 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
+ (either IPv4 or IPv6 address). If <var>ip</var> is an IPv6
+ address, wrap in square brackets,
+ e.g. <code>pssl:6640:[::1]</code>. If <var>ip</var> is not
+ specified then it listens only on IPv4 (but not IPv6) addresses.
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>
+ If <var>port</var> is not specified, it defaults to 6640.
+ </p>
<p>
SSL support is an optional feature that is not always built as
part of Open vSwitch.
</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.
+ <p>
+ Listens for connections on the specified TCP <var>port</var>.
+ Specify 0 for <var>port</var> to have the kernel automatically
+ choose an available port. 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
+ (either IPv4 or IPv6 address). If <var>ip</var> is an IPv6
+ address, wrap it in square brackets,
+ e.g. <code>ptcp:6640:[::1]</code>. If <var>ip</var> is not
+ specified then it listens only on IPv4 addresses.
+ </p>
+ <p>
+ If <var>port</var> is not specified, it defaults to 6640.
+ </p>
</dd>
</dl>
<p>When multiple managers are configured, the <ref column="target"/>
</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>
-
<group title="Status">
- <column name="is_connected">
+ <p>
+ Key-value pair of <ref column="is_connected"/> is always updated.
+ Other key-value pairs in the status columns may be updated depends
+ on the <ref column="target"/> type.
+ </p>
+
+ <p>
+ When <ref column="target"/> specifies a connection method that
+ listens for inbound connections (e.g. <code>ptcp:</code> or
+ <code>punix:</code>), both <ref column="n_connections"/> and
+ <ref column="is_connected"/> may also be updated while the
+ remaining key-value pairs are omitted.
+ </p>
+
+ <p>
+ On the other hand, when <ref column="target"/> specifies an
+ outbound connection, all key-value pairs may be updated, except
+ the above-mentioned two key-value pairs associated with inbound
+ connection targets. They are omitted.
+ </p>
+
+ <column name="is_connected">
<code>true</code> if currently connected to this manager,
<code>false</code> otherwise.
</column>
- <column name="status">
- <p>Key-value pairs that report manager status.</p>
- <dl>
- <dt><code>last_error</code></dt>
- <dd>A human-readable description of the last error on the connection
- to the manager; i.e. <code>strerror(errno)</code>. This key
- will exist only if an error has occurred.</dd>
- </dl>
- <dl>
- <dt><code>state</code></dt>
- <dd>The state of the connection to the manager. Possible values
- are: <code>VOID</code> (connection is disabled),
- <code>BACKOFF</code> (attempting to reconnect at an increasing
- period), <code>CONNECTING</code> (attempting to connect),
- <code>ACTIVE</code> (connected, remote host responsive), and
- <code>IDLE</code> (remote host idle, sending keep-alive). These
- values may change in the future. They are provided only for human
- consumption.</dd>
- </dl>
- <dl>
- <dt><code>sec_since_connect</code></dt>
- <dd>The amount of time since this manager last successfully connected
- to the database (in seconds). Value is empty if manager has never
- successfully connected.</dd>
- </dl>
- <dl>
- <dt><code>sec_since_disconnect</code></dt>
- <dd>The amount of time since this manager last disconnected from the
- database (in seconds). Value is empty if manager has never
- disconnected.</dd>
- </dl>
- <dl>
- <dt><code>locks_held</code></dt>
- <dt><code>locks_waiting</code></dt>
- <dt><code>locks_lost</code></dt>
- <dd>
- Space-separated lists of the names of OVSDB locks that the
- connection holds, is currently waiting to acquire, or has had
- stolen by another OVSDB client, respectively. Key-value pairs for
- lists that would be empty are omitted.
- </dd>
- </dl>
+ <column name="status" key="last_error">
+ A human-readable description of the last error on the connection
+ to the manager; i.e. <code>strerror(errno)</code>. This key
+ will exist only if an error has occurred.
+ </column>
+
+ <column name="status" key="state"
+ type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
+ <p>
+ The state of the connection to the manager:
+ </p>
<dl>
- <dt><code>n_connections</code></dt>
- <dd>
- <p>
- When <ref column="target"/> specifies a connection method that
- listens for inbound connections (e.g. <code>ptcp:</code> or
- <code>pssl:</code>) and more than one connection is actually
- active, the value is the number of active connections.
- Otherwise, this key-value pair is omitted.
- </p>
- <p>
- When multiple connections are active, status columns and
- key-value pairs (other than this one) report the status of one
- arbitrarily chosen connection.
- </p>
- </dd>
+ <dt><code>VOID</code></dt>
+ <dd>Connection is disabled.</dd>
+
+ <dt><code>BACKOFF</code></dt>
+ <dd>Attempting to reconnect at an increasing period.</dd>
+
+ <dt><code>CONNECTING</code></dt>
+ <dd>Attempting to connect.</dd>
+
+ <dt><code>ACTIVE</code></dt>
+ <dd>Connected, remote host responsive.</dd>
+
+ <dt><code>IDLE</code></dt>
+ <dd>Connection is idle. Waiting for response to keep-alive.</dd>
</dl>
+ <p>
+ These values may change in the future. They are provided only for
+ human consumption.
+ </p>
+ </column>
+
+ <column name="status" key="sec_since_connect"
+ type='{"type": "integer", "minInteger": 0}'>
+ The amount of time since this manager last successfully connected
+ to the database (in seconds). Value is empty if manager has never
+ successfully connected.
+ </column>
+
+ <column name="status" key="sec_since_disconnect"
+ type='{"type": "integer", "minInteger": 0}'>
+ The amount of time since this manager last disconnected from the
+ database (in seconds). Value is empty if manager has never
+ disconnected.
+ </column>
+
+ <column name="status" key="locks_held">
+ Space-separated list of the names of OVSDB locks that the connection
+ holds. Omitted if the connection does not hold any locks.
+ </column>
+
+ <column name="status" key="locks_waiting">
+ Space-separated list of the names of OVSDB locks that the connection is
+ currently waiting to acquire. Omitted if the connection is not waiting
+ for any locks.
+ </column>
+
+ <column name="status" key="locks_lost">
+ Space-separated list of the names of OVSDB locks that the connection
+ has had stolen by another OVSDB client. Omitted if no locks have been
+ stolen from this connection.
+ </column>
+
+ <column name="status" key="n_connections"
+ type='{"type": "integer", "minInteger": 2}'>
+ When <ref column="target"/> specifies a connection method that
+ listens for inbound connections (e.g. <code>ptcp:</code> or
+ <code>pssl:</code>) and more than one connection is actually active,
+ the value is the number of active connections. Otherwise, this
+ key-value pair is omitted.
+ </column>
+
+ <column name="status" key="bound_port" type='{"type": "integer"}'>
+ When <ref column="target"/> is <code>ptcp:</code> or
+ <code>pssl:</code>, this is the TCP port on which the OVSDB server is
+ listening. (This is particularly useful when <ref
+ column="target"/> specifies a port of 0, allowing the kernel to
+ choose any available port.)
+ </column>
+ </group>
+
+ <group title="Connection Parameters">
+ <p>
+ Additional configuration for a connection between the manager
+ and the Open vSwitch Database.
+ </p>
+
+ <column name="other_config" key="dscp"
+ type='{"type": "integer"}'>
+ The Differentiated Service Code Point (DSCP) is specified using 6 bits
+ in the Type of Service (TOS) field in the IP header. DSCP provides a
+ mechanism to classify the network traffic and provide Quality of
+ Service (QoS) on IP networks.
+
+ The DSCP value specified here is used when establishing the connection
+ between the manager and the Open vSwitch. If no value is specified, a
+ default value of 48 is chosen. Valid DSCP values must be in the range
+ 0 to 63.
</column>
</group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ <column name="other_config"/>
+ </group>
</table>
<table name="NetFlow">
</column>
<column name="active_timeout">
- The interval at which NetFlow records are sent for flows that are
- still active, in seconds. A value of <code>0</code> requests the
- default timeout (currently 600 seconds); a value of <code>-1</code>
- disables active timeouts.
+ <p>
+ The interval at which NetFlow records are sent for flows that
+ are still active, in seconds. A value of <code>0</code>
+ requests the default timeout (currently 600 seconds); a value
+ of <code>-1</code> disables active timeouts.
+ </p>
+
+ <p>
+ The NetFlow passive timeout, for flows that become inactive,
+ is not configurable. It will vary depending on the Open
+ vSwitch version, the forms and contents of the OpenFlow flow
+ tables, CPU and memory usage, and network activity. A typical
+ passive timeout is about a second.
+ </p>
</column>
<column name="add_id_to_interface">
<p>If this column's value is <code>false</code>, the ingress and egress
- interface fields of NetFlow flow records are derived from OpenFlow port
- numbers. When it is <code>true</code>, the 7 most significant bits of
- these fields will be replaced by the least significant 7 bits of the
- engine id. This is useful because many NetFlow collectors do not
- expect multiple switches to be sending messages from the same host, so
- they do not store the engine information which could be used to
- disambiguate the traffic.</p>
+ interface fields of NetFlow flow records are derived from OpenFlow port
+ numbers. When it is <code>true</code>, the 7 most significant bits of
+ these fields will be replaced by the least significant 7 bits of the
+ engine id. This is useful because many NetFlow collectors do not
+ expect multiple switches to be sending messages from the same host, so
+ they do not store the engine information which could be used to
+ 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>
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
</table>
<table name="SSL">
it will immediately drop the connection and reconnect, and from then
on all SSL connections must be authenticated by a certificate signed
by the CA certificate thus obtained. <em>This option exposes the
- SSL connection to a man-in-the-middle attack obtaining the initial
- CA certificate.</em> It may still be useful for bootstrapping.
+ 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>
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
</table>
<table name="sFlow">
- <p>An sFlow(R) target. sFlow is a protocol for remote monitoring
- of switches.</p>
+ <p>A set of sFlow(R) targets. sFlow is a protocol for remote
+ monitoring of switches.</p>
<column name="agent">
Name of the network device whose IP address should be reported as the
- ``agent address'' to collectors. If not specified, the IP address
+ ``agent address'' to collectors. If not specified, the agent device is
+ figured from the first target address and the routing table. If the
+ routing table does not contain a route to the target, the IP address
defaults to the <ref table="Controller" column="local_ip"/> in the
collector's <ref table="Controller"/>. If an agent IP address cannot be
- determined either way, sFlow is disabled.
+ determined any of these ways, sFlow is disabled.
</column>
<column name="header">
<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.
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="IPFIX">
+ <p>Configuration for sending packets to IPFIX collectors.</p>
+
+ <p>
+ IPFIX is a protocol that exports a number of details about flows. The
+ IPFIX implementation in Open vSwitch samples packets at a configurable
+ rate, extracts flow information from those packets, optionally caches and
+ aggregates the flow information, and sends the result to one or more
+ collectors.
+ </p>
+
+ <p>
+ IPFIX in Open vSwitch can be configured two different ways:
+ </p>
+
+ <ul>
+ <li>
+ With <em>per-bridge sampling</em>, Open vSwitch performs IPFIX sampling
+ automatically on all packets that pass through a bridge. To configure
+ per-bridge sampling, create an <ref table="IPFIX"/> record and point a
+ <ref table="Bridge"/> table's <ref table="Bridge" column="ipfix"/>
+ column to it. The <ref table="Flow_Sample_Collector_Set"/> table is
+ not used for per-bridge sampling.
+ </li>
+
+ <li>
+ <p>
+ With <em>flow-based sampling</em>, <code>sample</code> actions in the
+ OpenFlow flow table drive IPFIX sampling. See
+ <code>ovs-ofctl</code>(8) for a description of the
+ <code>sample</code> action.
+ </p>
+
+ <p>
+ Flow-based sampling also requires database configuration: create a
+ <ref table="IPFIX"/> record that describes the IPFIX configuration
+ and a <ref table="Flow_Sample_Collector_Set"/> record that points to
+ the <ref table="Bridge"/> whose flow table holds the
+ <code>sample</code> actions and to <ref table="IPFIX"/> record. The
+ <ref table="Bridge" column="ipfix"/> in the <ref table="Bridge"/>
+ table is not used for flow-based sampling.
+ </p>
+ </li>
+ </ul>
+
+ <column name="targets">
+ IPFIX target collectors in the form
+ <code><var>ip</var>:<var>port</var></code>.
+ </column>
+
+ <column name="cache_active_timeout">
+ The maximum period in seconds for which an IPFIX flow record is
+ cached and aggregated before being sent. If not specified,
+ defaults to 0. If 0, caching is disabled.
+ </column>
+
+ <column name="cache_max_flows">
+ The maximum number of IPFIX flow records that can be cached at a
+ time. If not specified, defaults to 0. If 0, caching is
+ disabled.
+ </column>
+
+ <group title="Per-Bridge Sampling">
+ <p>
+ These values affect only per-bridge sampling. See above for a
+ description of the differences between per-bridge and flow-based
+ sampling.
+ </p>
+
+ <column name="sampling">
+ The rate at which packets should be sampled and sent to each target
+ collector. If not specified, defaults to 400, which means one out of
+ 400 packets, on average, will be sent to each target collector.
+ </column>
+
+ <column name="obs_domain_id">
+ The IPFIX Observation Domain ID sent in each IPFIX packet. If not
+ specified, defaults to 0.
+ </column>
+
+ <column name="obs_point_id">
+ The IPFIX Observation Point ID sent in each IPFIX flow record. If not
+ specified, defaults to 0.
+ </column>
+
+ <column name="other_config" key="enable-tunnel-sampling"
+ type='{"type": "boolean"}'>
+ <p>
+ Set to <code>true</code> to enable sampling and reporting tunnel
+ header 7-tuples in IPFIX flow records. Tunnel sampling is disabled
+ by default.
+ </p>
+
+ <p>
+ The following enterprise entities report the sampled tunnel info:
+ </p>
+
+ <dl>
+ <dt>tunnelType:</dt>
+ <dd>
+ <p>ID: 891, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 8-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: Identifier of the layer 2 network overlay network
+ encapsulation type: 0x01 VxLAN, 0x02 GRE, 0x03 LISP, 0x05 IPsec+GRE,
+ 0x07 GENEVE.</p>
+ </dd>
+ <dt>tunnelKey:</dt>
+ <dd>
+ <p>ID: 892, and enterprise ID 6876 (VMware).</p>
+ <p>type: variable-length octetarray.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: Key which is used for identifying an individual
+ traffic flow within a VxLAN (24-bit VNI), GENEVE (24-bit VNI),
+ GRE (32-bit key), or LISP (24-bit instance ID) tunnel. The
+ key is encoded in this octetarray as a 3-, 4-, or 8-byte integer
+ ID in network byte order.</p>
+ </dd>
+ <dt>tunnelSourceIPv4Address:</dt>
+ <dd>
+ <p>ID: 893, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 32-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: The IPv4 source address in the tunnel IP packet
+ header.</p>
+ </dd>
+ <dt>tunnelDestinationIPv4Address:</dt>
+ <dd>
+ <p>ID: 894, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 32-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: The IPv4 destination address in the tunnel IP
+ packet header.</p>
+ </dd>
+ <dt>tunnelProtocolIdentifier:</dt>
+ <dd>
+ <p>ID: 895, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 8-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: The value of the protocol number in the tunnel
+ IP packet header. The protocol number identifies the tunnel IP
+ packet payload type.</p>
+ </dd>
+ <dt>tunnelSourceTransportPort:</dt>
+ <dd>
+ <p>ID: 896, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 16-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: The source port identifier in the tunnel transport
+ header. For the transport protocols UDP, TCP, and SCTP, this is
+ the source port number given in the respective header.</p>
+ </dd>
+ <dt>tunnelDestinationTransportPort:</dt>
+ <dd>
+ <p>ID: 897, and enterprise ID 6876 (VMware).</p>
+ <p>type: unsigned 16-bit integer.</p>
+ <p>data type semantics: identifier.</p>
+ <p>description: The destination port identifier in the tunnel
+ transport header. For the transport protocols UDP, TCP, and SCTP,
+ this is the destination port number given in the respective header.
+ </p>
+ </dd>
+ </dl>
+ </column>
+
+ <column name="other_config" key="enable-input-sampling"
+ type='{"type": "boolean"}'>
+ By default, Open vSwitch samples and reports flows at bridge port input
+ in IPFIX flow records. Set this column to <code>false</code> to
+ disable input sampling.
+ </column>
+
+ <column name="other_config" key="enable-output-sampling"
+ type='{"type": "boolean"}'>
+ By default, Open vSwitch samples and reports flows at bridge port
+ output in IPFIX flow records. Set this column to <code>false</code> to
+ disable output sampling.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Flow_Sample_Collector_Set">
+ <p>
+ A set of IPFIX collectors of packet samples generated by OpenFlow
+ <code>sample</code> actions. This table is used only for IPFIX
+ flow-based sampling, not for per-bridge sampling (see the <ref
+ table="IPFIX"/> table for a description of the two forms).
+ </p>
+
+ <column name="id">
+ The ID of this collector set, unique among the bridge's
+ collector sets, to be used as the <code>collector_set_id</code>
+ in OpenFlow <code>sample</code> actions.
+ </column>
+
+ <column name="bridge">
+ The bridge into which OpenFlow <code>sample</code> actions can
+ be added to send packet samples to this set of IPFIX collectors.
+ </column>
+
+ <column name="ipfix">
+ Configuration of the set of IPFIX collectors to send one flow
+ record per sampled packet to.
</column>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
</table>
- <table name="Capability">
- <p>Records in this table describe functionality supported by the hardware
- and software platform on which this Open vSwitch is based. Clients
- should not modify this table.</p>
+ <table name="AutoAttach">
+ <p>
+ Auto Attach configuration within a bridge. The IETF Auto-Attach SPBM
+ draft standard describes a compact method of using IEEE 802.1AB Link
+ Layer Discovery Protocol (LLDP) together with a IEEE 802.1aq Shortest
+ Path Bridging (SPB) network to automatically attach network devices
+ to individual services in a SPB network. The intent here is to allow
+ network applications and devices using OVS to be able to easily take
+ advantage of features offered by industry standard SPB networks.
+ </p>
- <p>A record in this table is meaningful only if it is referenced by the
- <ref table="Open_vSwitch" column="capabilities"/> column in the
- <ref table="Open_vSwitch"/> table. The key used to reference it, called
- the record's ``category,'' determines the meanings of the
- <ref column="details"/> column. The following general forms of
- categories are currently defined:</p>
+ <p>
+ Auto Attach (AA) uses LLDP to communicate between a directly connected
+ Auto Attach Client (AAC) and Auto Attach Server (AAS). The LLDP protocol
+ is extended to add two new Type-Length-Value tuples (TLVs). The first
+ new TLV supports the ongoing discovery of directly connected AA
+ correspondents. Auto Attach operates by regularly transmitting AA
+ discovery TLVs between the AA client and AA server. By exchanging these
+ discovery messages, both the AAC and AAS learn the system name and
+ system description of their peer. In the OVS context, OVS operates as
+ the AA client and the AA server resides on a switch at the edge of the
+ SPB network.
+ </p>
- <dl>
- <dt><code>qos-<var>type</var></code></dt>
- <dd><var>type</var> is supported as the value for
- <ref column="type" table="QoS"/> in the <ref table="QoS"/> table.
- </dd>
- </dl>
+ <p>
+ Once AA discovery has been completed the AAC then uses the second new TLV
+ to deliver identifier mappings from the AAC to the AAS. A primary feature
+ of Auto Attach is to facilitate the mapping of VLANs defined outside the
+ SPB network onto service ids (ISIDs) defined within the SPM network. By
+ doing so individual external VLANs can be mapped onto specific SPB
+ network services. These VLAN id to ISID mappings can be configured and
+ managed locally using new options added to the ovs-vsctl command.
+ </p>
+
+ <p>
+ The Auto Attach OVS feature does not provide a full implementation of
+ the LLDP protocol. Support for the mandatory TLVs as defined by the LLDP
+ standard and support for the AA TLV extensions is provided. LLDP
+ protocol support in OVS can be enabled or disabled on a port by port
+ basis. LLDP support is disabled by default.
+ </p>
- <column name="details">
- <p>Key-value pairs that describe capabilities. The meaning of the pairs
- depends on the category key that the <ref table="Open_vSwitch"
- column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
- uses to reference this record, as described above.</p>
+ <column name="system_name">
+ The system_name string is exported in LLDP messages. It should uniquely
+ identify the bridge in the network.
+ </column>
- <p>The presence of a record for category <code>qos-<var>type</var></code>
- indicates that the switch supports <var>type</var> as the value of
- the <ref table="QoS" column="type"/> column in the <ref table="QoS"/>
- table. The following key-value pairs are defined to further describe
- QoS capabilities:</p>
+ <column name="system_description">
+ The system_description string is exported in LLDP messages. It should
+ describe the type of software and hardware.
+ </column>
- <dl>
- <dt><code>n-queues</code></dt>
- <dd>Number of supported queues, as a positive integer. Keys in the
- <ref table="QoS" column="queues"/> column for <ref table="QoS"/>
- records whose <ref table="QoS" column="type"/> value
- equals <var>type</var> must range between 0 and this value minus one,
- inclusive.</dd>
- </dl>
+ <column name="mappings">
+ A mapping from SPB network Individual Service Identifier (ISID) to VLAN
+ id.
</column>
</table>
</database>
projects / cascardo / ovs.git / blobdiff