INSTALL.XenServer.md

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