INSTALL.XenServer.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ===============================================
  25 How to Install Open vSwitch on Citrix XenServer
  26 ===============================================
  27
  28 This document describes how to build and install Open vSwitch on a Citrix
  29 XenServer host.  If you want to install Open vSwitch on a generic Linux or BSD
  30 host, see the `installation guide <INSTALL.rst>`__ instead.
  31
  32 Open vSwitch should work with XenServer 5.6.100 and later.  However, Open
  33 vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5
  34 or earlier requires installing Python 2.7.
  35
  36 Building
  37 --------
  38
  39 You may build from an Open vSwitch distribution tarball or from an Open vSwitch
  40 Git tree.  The recommended build environment to build RPMs for Citrix XenServer
  41 is the DDK VM available from Citrix.
  42
  43 1. If you are building from an Open vSwitch Git tree, then you will need to
  44    first create a distribution tarball by running::
  45
  46        $ ./boot.sh
  47        $ ./configure
  48        $ make dist
  49
  50    You cannot run this in the DDK VM, because it lacks tools that are necessary
  51    to bootstrap the Open vSwitch distribution.  Instead, you must run this on a
  52    machine that has the tools listed in the installation guide <INSTALL.rst>`__
  53    as prerequisites for building from a Git tree.
  54
  55 2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside
  56    the DDK VM.
  57
  58 3. In the DDK VM, unpack the distribution tarball into a temporary directory
  59    and "cd" into the root of the distribution tarball.
  60
  61 4. To build Open vSwitch userspace, run::
  62
  63        $ rpmbuild -bb xenserver/openvswitch-xen.spec
  64
  65    This produces three RPMs in ``/usr/src/redhat/RPMS/i386``:
  66
  67    - ``openvswitch``
  68    - ``openvswitch-modules-xen``
  69    - ``openvswitch-debuginfo``
  70
  71    The above command automatically runs the Open vSwitch unit tests.  To
  72    disable the unit tests, run::
  73
  74        $ rpmbuild -bb --without check xenserver/openvswitch-xen.spec
  75
  76 Build Parameters
  77 ----------------
  78
  79 ``openvswitch-xen.spec`` needs to know a number of pieces of information about
  80 the XenServer kernel.  Usually, it can figure these out for itself, but if it
  81 does not do it correctly then you can specify them yourself as parameters to
  82 the build.  Thus, the final ``rpmbuild`` step above can be elaborated as::
  83
  84     $ VERSION=<Open vSwitch version>
  85     $ KERNEL_NAME=<Xen Kernel name>
  86     $ KERNEL_VERSION=<Xen Kernel version>
  87     $ KERNEL_FLAVOR=<Xen Kernel flavor(suffix)>
  88     $ rpmbuild \
  89          -D "openvswitch_version $VERSION" \
  90          -D "kernel_name $KERNEL_NAME" \
  91          -D "kernel_version $KERNEL_VERSION" \
  92          -D "kernel_flavor $KERNEL_FLAVOR" \
  93          -bb xenserver/openvswitch-xen.spec
  94
  95 where:
  96
  97 ``<openvswitch version>``
  98   is the version number that appears in the name of the Open vSwitch tarball,
  99   e.g. 0.90.0.
 100
 101 ``<Xen Kernel name>``
 102   is the name of the XenServer kernel package, e.g. ``kernel-xen`` or
 103   ``kernel-NAME-xen``, without the ``kernel-`` prefix.
 104
 105 ``<Xen Kernel version>``
 106   is the output of::
 107
 108       $ rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>,
 109
 110   e.g. ``2.6.32.12-0.7.1.xs5.6.100.323.170596``, where
 111   ``<kernel-devel-package>`` is the name of the ``-devel`` package
 112   corresponding to ``<Xen Kernel name>``.
 113
 114 ``<Xen Kernel flavor (suffix)>``
 115   is either ``xen`` or ``kdump``, where ``xen`` flavor is the main running
 116   kernel flavor and the ``kdump`` flavor is the crashdump kernel flavor.
 117   Commonly, one would specify ``xen`` here.
 118
 119 For XenServer 6.5 or above, the kernel version naming no longer contains
 120 KERNEL_FLAVOR.  In fact, only providing the ``uname -r`` output is enough.  So,
 121 the final ``rpmbuild`` step changes to::
 122
 123     $ KERNEL_UNAME=<`uname -r` output>
 124     $ rpmbuild \
 125         -D "kenel_uname $KERNEL_UNAME" \
 126         -bb xenserver/openvswitch-xen.spec
 127
 128 Installing Open vSwitch for XenServer
 129 -------------------------------------
 130
 131 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
 132 copy the ``openvswitch`` and ``openvswitch-modules-xen`` RPMs to that host with
 133 ``scp``, then install them with ``rpm -U``, e.g.::
 134
 135     $ scp openvswitch-$VERSION-1.i386.rpm \
 136         openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
 137         root@<host>:
 138     # Enter <host>'s root password.
 139     $ ssh root@<host>
 140     # Enter <host>'s root password again.
 141     $ rpm -U openvswitch-$VERSION-1.i386.rpm \
 142         openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
 143
 144 To uninstall Open vSwitch from a XenServer host, remove the packages::
 145
 146     $ ssh root@<host>
 147     # Enter <host>'s root password again.
 148     $ rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
 149
 150 After installing or uninstalling Open vSwitch, the XenServer should be rebooted
 151 as soon as possible.
 152
 153 Open vSwitch Boot Sequence on XenServer
 154 ---------------------------------------
 155
 156 When Open vSwitch is installed on XenServer, its startup script
 157 ``/etc/init.d/openvswitch`` runs early in boot.  It does roughly the following:
 158
 159 * Loads the OVS kernel module, openvswitch.
 160
 161 * Starts ovsdb-server, the OVS configuration database.
 162
 163 * XenServer expects there to be no bridges configured at startup, but the OVS
 164   configuration database likely still has bridges configured from before
 165   reboot.  To match XenServer expectations, the startup script deletes all
 166   configured bridges from the database.
 167
 168 * Starts ovs-vswitchd, the OVS switching daemon.
 169
 170 At this point in the boot process, then, there are no Open vSwitch bridges,
 171 even though all of the Open vSwitch daemons are running.  Later on in boot,
 172 ``/etc/init.d/management-interface`` (part of XenServer, not Open vSwitch)
 173 creates the bridge for the XAPI management interface by invoking
 174 ``/opt/xensource/libexec/interface-reconfigure``.  Normally this program
 175 consults XAPI's database to obtain information about how to configure the
 176 bridge, but XAPI is not running yet(\*) so it instead consults
 177 ``/var/xapi/network.dbcache``, which is a cached copy of the most recent
 178 network configuration.
 179
 180 (\*) Even if XAPI were running, if this XenServer node is a pool slave then the
 181      query would have to consult the master, which requires network access,
 182      which begs the question of how to configure the management interface.
 183
 184 XAPI starts later on in the boot process.  XAPI can then create other bridges
 185 on demand using ``/opt/xensource/libexec/interface-reconfigure``.  Now that
 186 XAPI is running, that program consults XAPI directly instead of reading the
 187 cache.
 188
 189 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin script
 190 ``/etc/xapi.d/openvswitch-cfg-update`` passing the ``update`` command.  The
 191 plugin script does roughly the following:
 192
 193 * Calls ``/opt/xensource/libexec/interface-reconfigure`` with the ``rewrite``
 194   command, to ensure that the network cache is up-to-date.
 195
 196 * Queries the Open vSwitch manager setting (named ``vswitch_controller``) from
 197   the XAPI database for the XenServer pool.
 198
 199 * If XAPI and OVS are configured for different managers, or if OVS is
 200   configured for a manager but XAPI is not, runs ``ovs-vsctl emer-reset`` to
 201   bring the Open vSwitch configuration to a known state.  One effect of
 202   emer-reset is to deconfigure any manager from the OVS database.
 203
 204 * If XAPI is configured for a manager, configures the OVS manager to match with
 205   ``ovs-vsctl set-manager``.
 206
 207 Notes
 208 -----
 209
 210 * The Open vSwitch boot sequence only configures an OVS configuration database
 211   manager.  There is no way to directly configure an OpenFlow controller on
 212   XenServer and, as a consequence of the step above that deletes all of the
 213   bridges at boot time, controller configuration only persists until XenServer
 214   reboot.  The configuration database manager can, however, configure
 215   controllers for bridges.  See the BUGS section of ovs-testcontroller(8) for
 216   more information on this topic.
 217
 218 * The Open vSwitch startup script automatically adds a firewall rule to allow
 219   GRE traffic. This rule is needed for the XenServer feature called "Cross-Host
 220   Internal Networks" (CHIN) that uses GRE. If a user configures tunnels other
 221   than GRE (ex: Geneve, VXLAN, LISP), they will have to either manually add a
 222   iptables firewall rule to allow the tunnel traffic or add it through a
 223   startup script (Please refer to the "enable-protocol" command in the
 224   ovs-ctl(8) manpage).
 225
 226 Reporting Bugs
 227 --------------
 228
 229 Please report problems to bugs@openvswitch.org.