Signed-off-by: Stephen Finucane <step...@that.guru> --- INSTALL.XenServer.rst | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL.rst | 2 +- Makefile.am | 2 +- README.md | 4 +- 4 files changed, 228 insertions(+), 4 deletions(-) create mode 100644 INSTALL.XenServer.rst
diff --git a/INSTALL.XenServer.rst b/INSTALL.XenServer.rst new file mode 100644 index 0000000..746b118 --- /dev/null +++ b/INSTALL.XenServer.rst @@ -0,0 +1,224 @@ +.. + 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. + +=============================================== +How to Install Open vSwitch on Citrix XenServer +=============================================== + +This document describes how to build and install Open vSwitch on a Citrix +XenServer host. If you want to install Open vSwitch on a generic Linux or BSD +host, see the `installation guide <INSTALL.rst>`__ instead. + +Open vSwitch should work with XenServer 5.6.100 and later. However, Open +vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5 +or earlier requires installing Python 2.7. + +Building +-------- + +You may build from an Open vSwitch distribution tarball or from an Open vSwitch +Git tree. The recommended build environment to build RPMs for Citrix XenServer +is the DDK VM available from Citrix. + +1. If you are building from an Open vSwitch Git tree, then you will need to + first create a distribution tarball by running::: + + $ ./boot.sh + $ ./configure + $ make dist + + You cannot run this in the DDK VM, because it lacks tools that are necessary + to bootstrap the Open vSwitch distribution. Instead, you must run this on a + machine that has the tools listed in the installation guide <INSTALL.rst>`__ + as prerequisites for building from a Git tree. + +2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside + the DDK VM. + +3. In the DDK VM, unpack the distribution tarball into a temporary directory + and "cd" into the root of the distribution tarball. + +4. To build Open vSwitch userspace, run::: + + $ rpmbuild -bb xenserver/openvswitch-xen.spec + + This produces three RPMs in ``/usr/src/redhat/RPMS/i386``: + + - ``openvswitch`` + - ``openvswitch-modules-xen`` + - ``openvswitch-debuginfo`` + + The above command automatically runs the Open vSwitch unit tests. To + disable the unit tests, run::: + + $ rpmbuild -bb --without check xenserver/openvswitch-xen.spec + +Build Parameters +---------------- + +``openvswitch-xen.spec`` needs to know a number of pieces of information about +the XenServer kernel. Usually, it can figure these out for itself, but if it +does not do it correctly then you can specify them yourself as parameters to +the build. Thus, the final ``rpmbuild`` step above can be elaborated as::: + + $ VERSION=<Open vSwitch version> + $ KERNEL_NAME=<Xen Kernel name> + $ KERNEL_VERSION=<Xen Kernel version> + $ KERNEL_FLAVOR=<Xen Kernel flavor(suffix)> + $ rpmbuild \ + -D "openvswitch_version $VERSION" \ + -D "kernel_name $KERNEL_NAME" \ + -D "kernel_version $KERNEL_VERSION" \ + -D "kernel_flavor $KERNEL_FLAVOR" \ + -bb xenserver/openvswitch-xen.spec + +where: + +``<openvswitch version>`` + is the version number that appears in the name of the Open vSwitch tarball, + e.g. 0.90.0. + +``<Xen Kernel name>`` + is the name of the XenServer kernel package, e.g. ``kernel-xen`` or + ``kernel-NAME-xen``, without the ``kernel-`` prefix. + +``<Xen Kernel version>`` + is the output of::: + + $ rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>, + + e.g. ``2.6.32.12-0.7.1.xs5.6.100.323.170596``, where + ``<kernel-devel-package>`` is the name of the ``-devel`` package + corresponding to ``<Xen Kernel name>``. + +``<Xen Kernel flavor (suffix)>`` + is either ``xen`` or ``kdump``, where ``xen`` flavor is the main running + kernel flavor and the ``kdump`` flavor is the crashdump kernel flavor. + Commonly, one would specify ``xen`` here. + +For XenServer 6.5 or above, the kernel version naming no longer contains +KERNEL_FLAVOR. In fact, only providing the ``uname -r`` output is enough. So, +the final ``rpmbuild`` step changes to::: + + $ KERNEL_UNAME=<`uname -r` output> + $ rpmbuild \ + -D "kenel_uname $KERNEL_UNAME" \ + -bb xenserver/openvswitch-xen.spec + +Installing Open vSwitch for XenServer +------------------------------------- + +To install Open vSwitch on a XenServer host, or to upgrade to a newer version, +copy the ``openvswitch`` and ``openvswitch-modules-xen`` RPMs to that host with +``scp``, then install them with ``rpm -U``, e.g.::: + + $ scp openvswitch-$VERSION-1.i386.rpm \ + openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \ + root@<host>: + # Enter <host>'s root password. + $ ssh root@<host> + # Enter <host>'s root password again. + $ rpm -U openvswitch-$VERSION-1.i386.rpm \ + openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm + +To uninstall Open vSwitch from a XenServer host, remove the packages::: + + $ ssh root@<host> + # Enter <host>'s root password again. + $ rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION + +After installing or uninstalling Open vSwitch, the XenServer should be rebooted +as soon as possible. + +Open vSwitch Boot Sequence on XenServer +--------------------------------------- + +When Open vSwitch is installed on XenServer, its startup script +``/etc/init.d/openvswitch`` runs early in boot. It does roughly the following: + +* Loads the OVS kernel module, openvswitch. + +* Starts ovsdb-server, the OVS configuration database. + +* XenServer expects there to be no bridges configured at startup, but the OVS + configuration database likely still has bridges configured from before + reboot. To match XenServer expectations, the startup script deletes all + configured bridges from the database. + +* Starts ovs-vswitchd, the OVS switching daemon. + +At this point in the boot process, then, there are no Open vSwitch bridges, +even though all of the Open vSwitch daemons are running. Later on in boot, +``/etc/init.d/management-interface`` (part of XenServer, not Open vSwitch) +creates the bridge for the XAPI management interface by invoking +``/opt/xensource/libexec/interface-reconfigure``. Normally this program +consults XAPI's database to obtain information about how to configure the +bridge, but XAPI is not running yet(\*) so it instead consults +``/var/xapi/network.dbcache``, which is a cached copy of the most recent +network configuration. + +(\*) Even if XAPI were running, if this XenServer node is a pool slave then the + query would have to consult the master, which requires network access, + which begs the question of how to configure the management interface. + +XAPI starts later on in the boot process. XAPI can then create other bridges +on demand using ``/opt/xensource/libexec/interface-reconfigure``. Now that +XAPI is running, that program consults XAPI directly instead of reading the +cache. + +As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin script +``/etc/xapi.d/openvswitch-cfg-update`` passing the ``update`` command. The +plugin script does roughly the following: + +* Calls ``/opt/xensource/libexec/interface-reconfigure`` with the ``rewrite`` + command, to ensure that the network cache is up-to-date. + +* Queries the Open vSwitch manager setting (named ``vswitch_controller``) from + the XAPI database for the XenServer pool. + +* If XAPI and OVS are configured for different managers, or if OVS is + configured for a manager but XAPI is not, runs ``ovs-vsctl emer-reset`` to + bring the Open vSwitch configuration to a known state. One effect of + emer-reset is to deconfigure any manager from the OVS database. + +* If XAPI is configured for a manager, configures the OVS manager to match with + ``ovs-vsctl set-manager``. + +Notes +----- + +* The Open vSwitch boot sequence only configures an OVS configuration database + manager. There is no way to directly configure an OpenFlow controller on + XenServer and, as a consequence of the step above that deletes all of the + bridges at boot time, controller configuration only persists until XenServer + reboot. The configuration database manager can, however, configure + controllers for bridges. See the BUGS section of ovs-testcontroller(8) for + more information on this topic. + +* The Open vSwitch startup script automatically adds a firewall rule to allow + GRE traffic. This rule is needed for the XenServer feature called "Cross-Host + Internal Networks" (CHIN) that uses GRE. If a user configures tunnels other + than GRE (ex: Geneve, VXLAN, LISP), they will have to either manually add a + iptables firewall rule to allow the tunnel traffic or add it through a + startup script (Please refer to the "enable-protocol" command in the + ovs-ctl(8) manpage). diff --git a/INSTALL.rst b/INSTALL.rst index b6c2ee1..2bde0f4 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -32,7 +32,7 @@ platform, refer to one of these installation guides: - `Debian <INSTALL.Debian.rst>`__ - `Fedora <INSTALL.Fedora.md>`__ - `RHEL <INSTALL.RHEL.md>`__ -- `XenServer <INSTALL.XenServer.md>`__ +- `XenServer <INSTALL.XenServer.rst>`__ - `NetBSD <INSTALL.NetBSD.md>`__ - `Windows <INSTALL.Windows.rst>`__ - `DPDK <INSTALL.DPDK.rst>`__ diff --git a/Makefile.am b/Makefile.am index 14ef77c..cf8aa43 100644 --- a/Makefile.am +++ b/Makefile.am @@ -82,7 +82,7 @@ docs = \ INSTALL.RHEL.md \ INSTALL.SELinux.md \ INSTALL.SSL.md \ - INSTALL.XenServer.md \ + INSTALL.XenServer.rst \ INSTALL.userspace.rst \ INSTALL.Windows.rst \ IntegrationGuide.md \ diff --git a/README.md b/README.md index f853839..8ff5f5d 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ platform, please see one of these files: - [INSTALL.Debian.rst] - [INSTALL.Fedora.md] - [INSTALL.RHEL.md] -- [INSTALL.XenServer.md] +- [INSTALL.XenServer.rst] To use Open vSwitch... @@ -126,6 +126,6 @@ b...@openvswitch.org [INSTALL.SELinux.md]:INSTALL.SELinux.md [INSTALL.SSL.md]:INSTALL.SSL.md [INSTALL.userspace.rst]:INSTALL.userspace.rst -[INSTALL.XenServer.md]:INSTALL.XenServer.md +[INSTALL.XenServer.rst]:INSTALL.XenServer.rst [FAQ.md]:FAQ.md [tutorial/Tutorial.md]:tutorial/Tutorial.md -- 2.7.4 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
