deleted file mode 100644
@@ -1,169 +0,0 @@
-Integration Guide for Centralized Control
-=========================================
-
-This document describes how to integrate Open vSwitch onto a new
-platform to expose the state of the switch and attached devices for
-centralized control. (If you are looking to port the switching
-components of Open vSwitch to a new platform, please see the PORTING
-document.) The focus of this guide is on hypervisors, but many of the
-interfaces are useful for hardware switches, as well. The XenServer
-integration is the most mature implementation, so most of the examples
-are drawn from it.
-
-The externally visible interface to this integration is
-platform-agnostic. We encourage anyone who integrates Open vSwitch to
-use the same interface, because keeping a uniform interface means that
-controllers require less customization for individual platforms (and
-perhaps no customization at all).
-
-Integration centers around the Open vSwitch database and mostly involves
-the 'external_ids' columns in several of the tables. These columns are
-not interpreted by Open vSwitch itself. Instead, they provide
-information to a controller that permits it to associate a database
-record with a more meaningful entity. In contrast, the 'other_config'
-column is used to configure behavior of the switch. The main job of the
-integrator, then, is to ensure that these values are correctly populated
-and maintained.
-
-An integrator sets the columns in the database by talking to the
-ovsdb-server daemon. A few of the columns can be set during startup by
-calling the ovs-ctl tool from inside the startup scripts. The
-'xenserver/etc_init.d_openvswitch' script provides examples of its use,
-and the ovs-ctl(8) manpage contains complete documentation. At runtime,
-ovs-vsctl can be be used to set columns in the database. The script
-'xenserver/etc_xensource_scripts_vif' contains examples of its use, and
-ovs-vsctl(8) manpage contains complete documentation.
-
-Python and C bindings to the database are provided if deeper integration
-with a program are needed. The XenServer ovs-xapi-sync daemon
-('xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync') provides an
-example of using the Python bindings. More information on the python
-bindings is available at 'python/ovs/db/idl.py'. Information on the C
-bindings is available at 'lib/ovsdb-idl.h'.
-
-The following diagram shows how integration scripts fit into the Open vSwitch
-architecture:
-
- +----------------------------------------+
- | Controller Cluster +
- +----------------------------------------+
- |
- |
- +----------------------------------------------------------+
- | | |
- | +--------------+---------------+ |
- | | | |
- | +-------------------+ +------------------+ |
- | | ovsdb-server |-----------| ovs-vswitchd | |
- | +-------------------+ +------------------+ |
- | | | |
- | +---------------------+ | |
- | | Integration scripts | | |
- | | (ex: ovs-xapi-sync) | | |
- | +---------------------+ | |
- | | Userspace |
- |----------------------------------------------------------|
- | | Kernel |
- | | |
- | +---------------------+ |
- | | OVS Kernel Module | |
- | +---------------------+ |
- +----------------------------------------------------------+
-
-
-A description of the most relevant fields for integration follows. By
-setting these values, controllers are able to understand the network and
-manage it more dynamically and precisely. For more details about the
-database and each individual column, please refer to the
-ovs-vswitchd.conf.db(5) manpage.
-
-
-Open_vSwitch table
-------------------
-The Open_vSwitch table describes the switch as a whole. The
-'system_type' and 'system_version' columns identify the platform to the
-controller. The 'external_ids:system-id' key uniquely identifies the
-physical host. In XenServer, the system-id will likely be the same as
-the UUID returned by 'xe host-list'. This key allows controllers to
-distinguish between multiple hypervisors.
-
-Most of this configuration can be done with the ovs-ctl command at
-startup. For example:
-
- ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
- --system-id="${UUID}" "${other_options}" start
-
-Alternatively, the ovs-vsctl command may be used to set a particular
-value at runtime. For example:
-
- ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
-
-The 'other_config:enable-statistics' key may be set to "true" to have OVS
-populate the database with statistics (e.g., number of CPUs, memory,
-system load) for the controller's use.
-
-
-Bridge table
-------------
-The Bridge table describes individual bridges within an Open vSwitch
-instance. The 'external-ids:bridge-id' key uniquely identifies a
-particular bridge. In XenServer, this will likely be the same as the
-UUID returned by 'xe network-list' for that particular bridge.
-
-For example, to set the identifier for bridge "br0", the following
-command can be used:
-
- ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
-
-The MAC address of the bridge may be manually configured by setting it
-with the "other_config:hwaddr" key. For example:
-
- ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
-
-
-Interface table
----------------
-The Interface table describes an interface under the control of Open
-vSwitch. The 'external_ids' column contains keys that are used to
-provide additional information about the interface:
-
- attached-mac
-
- This field contains the MAC address of the device attached to
- the interface. On a hypervisor, this is the MAC address of the
- interface as seen inside a VM. It does not necessarily
- correlate to the host-side MAC address. For example, on
- XenServer, the MAC address on a VIF in the hypervisor is always
- FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is
- seen.
-
- iface-id
-
- This field uniquely identifies the interface. In hypervisors,
- this allows the controller to follow VM network interfaces as
- VMs migrate. A well-chosen identifier should also allow an
- administrator or a controller to associate the interface with
- the corresponding object in the VM management system. For
- example, the Open vSwitch integration with XenServer by default
- uses the XenServer assigned UUID for a VIF record as the
- iface-id.
-
- iface-status
-
- In a hypervisor, there are situations where there are multiple
- interface choices for a single virtual ethernet interface inside
- a VM. Valid values are "active" and "inactive". A complete
- description is available in the ovs-vswitchd.conf.db(5) manpage.
-
- vm-id
-
- This field uniquely identifies the VM to which this interface
- belongs. A single VM may have multiple interfaces attached to
- it.
-
-As in the previous tables, the ovs-vsctl command may be used to
-configure the values. For example, to set the 'iface-id' on eth0, the
-following command can be used:
-
- ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'
-
new file mode 100644
@@ -0,0 +1,195 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ ======= Heading 0 (reserved for the title in a document)
+ ------- Heading 1
+ ~~~~~~~ Heading 2
+ +++++++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+=========================================
+Integration Guide for Centralized Control
+=========================================
+
+This document describes how to integrate Open vSwitch onto a new platform to
+expose the state of the switch and attached devices for centralized control.
+(If you are looking to port the switching components of Open vSwitch to a new
+platform, please see the PORTING document.) The focus of this guide is on
+hypervisors, but many of the interfaces are useful for hardware switches, as
+well. The XenServer integration is the most mature implementation, so most of
+the examples are drawn from it.
+
+The externally visible interface to this integration is platform-agnostic. We
+encourage anyone who integrates Open vSwitch to use the same interface, because
+keeping a uniform interface means that controllers require less customization
+for individual platforms (and perhaps no customization at all).
+
+Integration centers around the Open vSwitch database and mostly involves the
+``external_ids`` columns in several of the tables. These columns are not
+interpreted by Open vSwitch itself. Instead, they provide information to a
+controller that permits it to associate a database record with a more
+meaningful entity. In contrast, the ``other_config`` column is used to
+configure behavior of the switch. The main job of the integrator, then, is to
+ensure that these values are correctly populated and maintained.
+
+An integrator sets the columns in the database by talking to the ovsdb-server
+daemon. A few of the columns can be set during startup by calling the ovs-ctl
+tool from inside the startup scripts. The ``xenserver/etc_init.d_openvswitch``
+script provides examples of its use, and the ovs-ctl(8) manpage contains
+complete documentation. At runtime, ovs-vsctl can be be used to set columns in
+the database. The script ``xenserver/etc_xensource_scripts_vif`` contains
+examples of its use, and ovs-vsctl(8) manpage contains complete documentation.
+
+Python and C bindings to the database are provided if deeper integration with a
+program are needed. The XenServer ovs-xapi-sync daemon
+(``xenserver/usr_share_openvswitch_scripts_ovs-xapi-sync``) provides an example
+of using the Python bindings. More information on the python bindings is
+available at ``python/ovs/db/idl.py``. Information on the C bindings is
+available at ``lib/ovsdb-idl.h``.
+
+The following diagram shows how integration scripts fit into the Open vSwitch
+architecture:
+
+::
+
+ Diagram
+
+ +----------------------------------------+
+ | Controller Cluster +
+ +----------------------------------------+
+ |
+ |
+ +----------------------------------------------------------+
+ | | |
+ | +--------------+---------------+ |
+ | | | |
+ | +-------------------+ +------------------+ |
+ | | ovsdb-server |-----------| ovs-vswitchd | |
+ | +-------------------+ +------------------+ |
+ | | | |
+ | +---------------------+ | |
+ | | Integration scripts | | |
+ | | (ex: ovs-xapi-sync) | | |
+ | +---------------------+ | |
+ | | Userspace |
+ |----------------------------------------------------------|
+ | | Kernel |
+ | | |
+ | +---------------------+ |
+ | | OVS Kernel Module | |
+ | +---------------------+ |
+ +----------------------------------------------------------+
+
+A description of the most relevant fields for integration follows. By setting
+these values, controllers are able to understand the network and manage it more
+dynamically and precisely. For more details about the database and each
+individual column, please refer to the ovs-vswitchd.conf.db(5) manpage.
+
+``Open_vSwitch`` table
+----------------------
+
+The ``Open_vSwitch`` table describes the switch as a whole. The
+``system_type`` and ``system_version`` columns identify the platform to the
+controller. The ``external_ids:system-id`` key uniquely identifies the
+physical host. In XenServer, the system-id will likely be the same as the UUID
+returned by ``xe host-list``. This key allows controllers to distinguish
+between multiple hypervisors.
+
+Most of this configuration can be done with the ovs-ctl command at startup.
+For example:
+
+::
+
+ $ ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
+ --system-id="${UUID}" "${other_options}" start
+
+Alternatively, the ovs-vsctl command may be used to set a particular value at
+runtime. For example:
+
+::
+
+ $ ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
+
+The ``other_config:enable-statistics`` key may be set to ``true`` to have OVS
+populate the database with statistics (e.g., number of CPUs, memory, system
+load) for the controller's use.
+
+Bridge table
+------------
+
+The Bridge table describes individual bridges within an Open vSwitch instance.
+The ``external-ids:bridge-id`` key uniquely identifies a particular bridge. In
+XenServer, this will likely be the same as the UUID returned by ``xe
+network-list`` for that particular bridge.
+
+For example, to set the identifier for bridge "br0", the following command can
+be used:
+
+::
+
+ $ ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
+
+The MAC address of the bridge may be manually configured by setting it with the
+``other_config:hwaddr`` key. For example:
+
+::
+
+ $ ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
+
+Interface table
+---------------
+
+The Interface table describes an interface under the control of Open vSwitch.
+The ``external_ids`` column contains keys that are used to provide additional
+information about the interface:
+
+attached-mac
+
+ This field contains the MAC address of the device attached to the interface.
+ On a hypervisor, this is the MAC address of the interface as seen inside a
+ VM. It does not necessarily correlate to the host-side MAC address. For
+ example, on XenServer, the MAC address on a VIF in the hypervisor is always
+ FE:FF:FF:FF:FF:FF, but inside the VM a normal MAC address is seen.
+
+iface-id
+
+ This field uniquely identifies the interface. In hypervisors, this allows
+ the controller to follow VM network interfaces as VMs migrate. A well-chosen
+ identifier should also allow an administrator or a controller to associate
+ the interface with the corresponding object in the VM management system. For
+ example, the Open vSwitch integration with XenServer by default uses the
+ XenServer assigned UUID for a VIF record as the iface-id.
+
+iface-status
+
+ In a hypervisor, there are situations where there are multiple interface
+ choices for a single virtual ethernet interface inside a VM. Valid values
+ are "active" and "inactive". A complete description is available in the
+ ovs-vswitchd.conf.db(5) manpage.
+
+vm-id
+
+ This field uniquely identifies the VM to which this interface belongs. A
+ single VM may have multiple interfaces attached to it.
+
+As in the previous tables, the ovs-vsctl command may be used to configure the
+values. For example, to set the ``iface-id`` on eth0, the following command
+can be used:
+
+::
+
+ $ ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'
@@ -85,7 +85,7 @@ docs = \
INSTALL.XenServer.rst \
INSTALL.userspace.rst \
INSTALL.Windows.rst \
- IntegrationGuide.md \
+ IntegrationGuide.rst \
MAINTAINERS.md \
OPENFLOW-1.1+.md \
PORTING.md \
@@ -22,7 +22,7 @@ interface (VIF) of VM-A.
* When VM-A is created on a hypervisor, its VIF gets added to the
Open vSwitch integration bridge. This creates a row in the Interface table
-of the Open_vSwitch database. As explained in the [IntegrationGuide.md],
+of the Open_vSwitch database. As explained in the [IntegrationGuide.rst],
the vif-id associated with the VM network interface gets added in the
external_ids:iface-id column of the newly created row in the Interface table.
@@ -119,4 +119,4 @@ a MAC address and IP address for that interface. ovn-docker will then create
a veth pair, insert one end inside the container as 'eth0' and the other end
as a port of a local OVS bridge as an access port of the chosen VLAN.
-[IntegrationGuide.md]:IntegrationGuide.md
+[IntegrationGuide.rst]:IntegrationGuide.rst
@@ -42,7 +42,7 @@
<li>
One or more (usually many) <dfn>hypervisors</dfn>. Hypervisors must run
Open vSwitch and implement the interface described in
- <code>IntegrationGuide.md</code> in the OVS source tree. Any hypervisor
+ <code>IntegrationGuide.rst</code> in the OVS source tree. Any hypervisor
platform supported by Open vSwitch is acceptable.
</li>
@@ -295,7 +295,7 @@
<li>
On a hypervisor, any VIFs that are to be attached to logical networks.
The hypervisor itself, or the integration between Open vSwitch and the
- hypervisor (described in <code>IntegrationGuide.md</code>) takes care of
+ hypervisor (described in <code>IntegrationGuide.rst</code>) takes care of
this. (This is not part of OVN or new to OVN; this is pre-existing
integration work that has already been done on hypervisors that support
OVS.)
@@ -445,7 +445,7 @@
<li>
Eventually, a user powers on the VM that owns the VIF. On the hypervisor
where the VM is powered on, the integration between the hypervisor and
- Open vSwitch (described in <code>IntegrationGuide.md</code>) adds the VIF
+ Open vSwitch (described in <code>IntegrationGuide.rst</code>) adds the VIF
to the OVN integration bridge and stores <var>vif-id</var> in
<code>external_ids</code>:<code>iface-id</code> to indicate that the
interface is an instantiation of the new VIF. (None of this code is new
@@ -1593,7 +1593,7 @@ tcp.flags = RST;
which <code>ovn-controller</code>/<code>ovn-controller-vtep</code> in
turn finds out by monitoring the local hypervisor's Open_vSwitch
database, which identifies logical ports via the conventions described
- in <code>IntegrationGuide.md</code>. (The exceptions are for
+ in <code>IntegrationGuide.rst</code>. (The exceptions are for
<code>Port_Binding</code> records with <code>type</code> of
<code>l3gateway</code>, whose locations are identified by
<code>ovn-northd</code> via the <code>options:l3gateway-chassis</code>
Signed-off-by: Stephen Finucane <stephen@that.guru> --- IntegrationGuide.md | 169 -------------------------------------- IntegrationGuide.rst | 195 ++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- ovn/CONTAINERS.OpenStack.md | 4 +- ovn/ovn-architecture.7.xml | 6 +- ovn/ovn-sb.xml | 2 +- 6 files changed, 202 insertions(+), 176 deletions(-) delete mode 100644 IntegrationGuide.md create mode 100644 IntegrationGuide.rst