From patchwork Tue Oct 18 20:03:32 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 683846 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3sz5dx12gXz9s2G for ; Wed, 19 Oct 2016 07:05:09 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=ENrr1WyL; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 5870910325; Tue, 18 Oct 2016 13:05:08 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e4.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id C8D2210315 for ; Tue, 18 Oct 2016 13:05:06 -0700 (PDT) Received: from bar5.cudamail.com (unknown [192.168.21.12]) by mx1e4.cudamail.com (Postfix) with ESMTPS id 512741E05B7 for ; Tue, 18 Oct 2016 14:05:06 -0600 (MDT) X-ASG-Debug-ID: 1476821105-09eadd6af3122ed0001-byXFYA Received: from mx1-pf1.cudamail.com ([192.168.24.1]) by bar5.cudamail.com with ESMTP id rsA2DSYRMHTicOvX (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Tue, 18 Oct 2016 14:05:05 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.24.1 Received: from unknown (HELO bongo.birch.relay.mailchannels.net) (23.83.209.21) by mx1-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 18 Oct 2016 20:05:04 -0000 Received-SPF: none (mx1-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.21 X-Barracuda-RBL-IP: 23.83.209.21 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id EA192203D5 for ; Tue, 18 Oct 2016 20:05:02 +0000 (UTC) Received: from one.mxroute.com (ip-10-107-69-155.us-west-2.compute.internal [10.107.69.155]) by relay.mailchannels.net (Postfix) with ESMTPA id 10D322064B for ; Tue, 18 Oct 2016 20:05:01 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([TEMPUNAVAIL]. [10.102.194.57]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Tue, 18 Oct 2016 20:05:02 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1476821102447:2637152042 X-MC-Ingress-Time: 1476821102446 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=moM/zBrurw8wNLZpA7xHuIfsCnTKXi73hJiizOab+gM=; b=ENrr1WyL0Bcd0TauqWYXT/hPQn tPg5GJTTCthJIyEip7svfOgSvnil42NaTy0CEkKzi6rp9B8/0e59TZer0SAzMCFo73o9nHnlLiSs9 6nZvyD3xCtWaRcMQlRZmxAFjWar5U3MtSsm5YAJ/E6RZlc6YEZRJg3ed8R1FUaaueDxdtgQTkkLBs +6rZyIBlVHbdMRG74JqOa5TXWNJs9z9hrKqDZGiGgkn1j1mgKp6fLPLTTf91GAKNCWjL+nY0ERRoe pGL5SMeTSuo3gClSNTgK1nHimMm7G5STJVmPHWudBWE8dJau7ZSpIgzD9UI9nMqrBs/Ts5WbB7rx7 7yQouaMQ==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-E1-1017071287 X-CudaMail-DTE: 101816 X-CudaMail-Originating-IP: 23.83.209.21 Date: Tue, 18 Oct 2016 21:03:32 +0100 X-ASG-Orig-Subj: [##CM-E1-1017071287##][PATCH 02/15] doc: Convert IntegrationGuide to rST Message-Id: <1476821025-4915-3-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1476821025-4915-1-git-send-email-stephen@that.guru> References: <1476821025-4915-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-Barracuda-Connect: UNKNOWN[192.168.24.1] X-Barracuda-Start-Time: 1476821105 X-Barracuda-Encrypted: ECDHE-RSA-AES256-GCM-SHA384 X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.60 X-Barracuda-Spam-Status: No, SCORE=1.60 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_RULE7568M, BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.33831 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.50 BSF_RULE7568M Custom Rule 7568M 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 02/15] doc: Convert IntegrationGuide to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- 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 @@
  • One or more (usually many) hypervisors. Hypervisors must run Open vSwitch and implement the interface described in - IntegrationGuide.md in the OVS source tree. Any hypervisor + IntegrationGuide.rst in the OVS source tree. Any hypervisor platform supported by Open vSwitch is acceptable.
    • @@ -295,7 +295,7 @@
  • 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 IntegrationGuide.md) takes care of + hypervisor (described in IntegrationGuide.rst) 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 @@
  • 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 IntegrationGuide.md) adds the VIF + Open vSwitch (described in IntegrationGuide.rst) adds the VIF to the OVN integration bridge and stores vif-id in external_ids:iface-id 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 ovn-controller/ovn-controller-vtep in turn finds out by monitoring the local hypervisor's Open_vSwitch database, which identifies logical ports via the conventions described - in IntegrationGuide.md. (The exceptions are for + in IntegrationGuide.rst. (The exceptions are for Port_Binding records with type of l3gateway, whose locations are identified by ovn-northd via the options:l3gateway-chassis