doc: Convert IntegrationGuide to rST

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

IntegrationGuide.rst

@@ -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}"'

Makefile.am

@@ -86,7 +86,7 @@ docs = \
 	INSTALL.XenServer.rst \
 	INSTALL.userspace.rst \
 	INSTALL.Windows.rst \
-	IntegrationGuide.md \
+	IntegrationGuide.rst \
 	MAINTAINERS.md \
 	OPENFLOW-1.1+.md \
 	PORTING.md \

ovn/CONTAINERS.OpenStack.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