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.  Correspondingly, the the final "rpmbuild" step changes to:
  85
  86    ```
  87    VERSION=<Open vSwitch version>
  88    KERNEL_NAME=<Xen Kernel name>
  89    KERNEL_VERSION=<Xen Kernel version>
  90    XEN_VERSION=<Xen Kernel flavor(suffix) >
  91    rpmbuild \
  92         -D "openvswitch_version $VERSION" \
  93         -D "kernel_name $KERNEL_NAME" \
  94         -D "kernel_version $KERNEL_VERSION" \
  95         -D "xen_version $XEN_VERSION" \
  96         -bb xenserver/openvswitch-xen.spec
  97    ```
  98
  99 where:
 100
 101     `<Xen Version>` is the output of `uname -r`.  Since XenServer 6.5, the
 102     directory name in 'lib/modules/' becomes a shortened expression of the
 103     KERNEL_VERSION.
 104
 105 Installing Open vSwitch for XenServer
 106 -------------------------------------
 107
 108 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
 109 copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
 110 "scp", then install them with "rpm -U", e.g.:
 111
 112      ```
 113      scp openvswitch-$VERSION-1.i386.rpm \
 114          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
 115          root@<host>:
 116 (At this point you will have to enter <host>'s root password.)
 117      ssh root@<host>
 118 (At this point you will have to enter <host>'s root password again.)
 119      rpm -U openvswitch-$VERSION-1.i386.rpm \
 120          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
 121      ```
 122
 123 To uninstall Open vSwitch from a XenServer host, remove the packages:
 124
 125      `ssh root@<host>`
 126 (At this point you will have to enter <host>'s root password again.)
 127      `rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION`
 128
 129 After installing or uninstalling Open vSwitch, the XenServer should be
 130 rebooted as soon as possible.
 131
 132 Open vSwitch Boot Sequence on XenServer
 133 ---------------------------------------
 134
 135 When Open vSwitch is installed on XenServer, its startup script
 136 /etc/init.d/openvswitch runs early in boot.  It does roughly the
 137 following:
 138
 139         * Loads the OVS kernel module, openvswitch.
 140
 141         * Starts ovsdb-server, the OVS configuration database.
 142
 143         * XenServer expects there to be no bridges configured at
 144           startup, but the OVS configuration database likely still has
 145           bridges configured from before reboot.  To match XenServer
 146           expectations, the startup script deletes all configured
 147           bridges from the database.
 148
 149         * Starts ovs-vswitchd, the OVS switching daemon.
 150
 151 At this point in the boot process, then, there are no Open vSwitch
 152 bridges, even though all of the Open vSwitch daemons are running.
 153 Later on in boot, /etc/init.d/management-interface (part of XenServer,
 154 not Open vSwitch) creates the bridge for the XAPI management interface
 155 by invoking /opt/xensource/libexec/interface-reconfigure.  Normally
 156 this program consults XAPI's database to obtain information about how
 157 to configure the bridge, but XAPI is not running yet[*] so it instead
 158 consults /var/xapi/network.dbcache, which is a cached copy of the most
 159 recent network configuration.
 160
 161 [*] Even if XAPI were running, if this XenServer node is a pool slave
 162     then the query would have to consult the master, which requires
 163     network access, which begs the question of how to configure the
 164     management interface.
 165
 166 XAPI starts later on in the boot process.  XAPI can then create other
 167 bridges on demand using /opt/xensource/libexec/interface-reconfigure.
 168 Now that XAPI is running, that program consults XAPI directly instead
 169 of reading the cache.
 170
 171 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
 172 script /etc/xapi.d/openvswitch-cfg-update passing the "update"
 173 command.  The plugin script does roughly the following:
 174
 175         * Calls /opt/xensource/libexec/interface-reconfigure with the
 176           "rewrite" command, to ensure that the network cache is
 177           up-to-date.
 178
 179         * Queries the Open vSwitch manager setting (named
 180           "vswitch_controller") from the XAPI database for the
 181           XenServer pool.
 182
 183         * If XAPI and OVS are configured for different managers, or if
 184           OVS is configured for a manager but XAPI is not, runs
 185           "ovs-vsctl emer-reset" to bring the Open vSwitch
 186           configuration to a known state.  One effect of emer-reset is
 187           to deconfigure any manager from the OVS database.
 188
 189         * If XAPI is configured for a manager, configures the OVS
 190           manager to match with "ovs-vsctl set-manager".
 191
 192 Notes
 193 -----
 194
 195 * The Open vSwitch boot sequence only configures an OVS configuration
 196 database manager.  There is no way to directly configure an OpenFlow
 197 controller on XenServer and, as a consequence of the step above that
 198 deletes all of the bridges at boot time, controller configuration only
 199 persists until XenServer reboot.  The configuration database manager
 200 can, however, configure controllers for bridges.  See the BUGS section
 201 of ovs-testcontroller(8) for more information on this topic.
 202
 203 * The Open vSwitch startup script automatically adds a firewall rule
 204 to allow GRE traffic. This rule is needed for the XenServer feature
 205 called "Cross-Host Internal Networks" (CHIN) that uses GRE. If a user
 206 configures tunnels other than GRE (ex: Geneve, VXLAN, LISP), they will have
 207 to either manually add a iptables firewall rule to allow the tunnel traffic
 208 or add it through a startup script (Please refer to the "enable-protocol"
 209 command in the ovs-ctl(8) manpage).
 210
 211 Reporting Bugs
 212 --------------
 213
 214 Please report problems to bugs@openvswitch.org.
 215
 216 [INSTALL.md]:INSTALL.md