[ovs-dev] [PATCH 02/15] doc: Convert IntegrationGuide to rST

Stephen Finucane stephen at that.guru
Tue Oct 18 20:03:32 UTC 2016


Signed-off-by: Stephen Finucane <stephen at 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

diff --git a/IntegrationGuide.md b/IntegrationGuide.md
deleted file mode 100644
index 5d3e574..0000000
--- a/IntegrationGuide.md
+++ /dev/null
@@ -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}"'
-
diff --git a/IntegrationGuide.rst b/IntegrationGuide.rst
new file mode 100644
index 0000000..4a591fa
--- /dev/null
+++ b/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}"'
diff --git a/Makefile.am b/Makefile.am
index 8b521cb..5f0cdd8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -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 \
diff --git a/ovn/CONTAINERS.OpenStack.md b/ovn/CONTAINERS.OpenStack.md
index d640d7c..8f74e6f 100644
--- a/ovn/CONTAINERS.OpenStack.md
+++ b/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
diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml
index de2a376..bc5dfb7 100644
--- a/ovn/ovn-architecture.7.xml
+++ b/ovn/ovn-architecture.7.xml
@@ -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
diff --git a/ovn/ovn-sb.xml b/ovn/ovn-sb.xml
index b484f59..4e0047a 100644
--- a/ovn/ovn-sb.xml
+++ b/ovn/ovn-sb.xml
@@ -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>
-- 
2.7.4




More information about the dev mailing list