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