INSTALL.XenServer

   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 host, see INSTALL.Linux instead.
   7
   8 These instructions have been tested with XenServer 5.6 FP1.
   9
  10 Building Open vSwitch for XenServer
  11 -----------------------------------
  12
  13 The recommended build environment to build RPMs for Citrix XenServer
  14 is the DDK VM available from Citrix.  If you are building from an Open
  15 vSwitch distribution tarball, this VM has all the tools that you will
  16 need.  If you are building from an Open vSwitch Git tree, then you
  17 will need to first create a distribution tarball elsewhere, by running
  18 "./boot.sh; ./configure; make dist" in the Git tree, because the DDK
  19 VM does not include Autoconf or Automake that are required to
  20 bootstrap the Open vSwitch distribution.
  21
  22 Once you have a distribution tarball, copy it into
  23 /usr/src/redhat/SOURCES inside the VM.  Then execute the following:
  24
  25    VERSION=<Open vSwitch version>
  26    XENKERNEL=<Xen kernel version>
  27    cd /tmp
  28    tar xfz /usr/src/redhat/SOURCES/openvswitch-$VERSION.tar.gz
  29    rpmbuild \
  30         -D "openvswitch_version $VERSION" \
  31         -D "xen_version $XENKERNEL" \
  32         -bb openvswitch-$VERSION/xenserver/openvswitch-xen.spec
  33
  34 where:
  35
  36     <openvswitch version> is the version number that appears in the
  37     name of the Open vSwitch tarball, e.g. 0.90.0.
  38
  39     <Xen kernel version> is the version number of the Xen kernel,
  40     e.g. 2.6.32.12-0.7.1.xs5.6.100.307.170586xen.  This version number
  41     appears as the name of a directory in /lib/modules inside the VM.
  42     It always ends in "xen".
  43
  44 Three RPMs will be output into /usr/src/redhat/RPMS/i386, whose names begin
  45 with "openvswitch", "openvswitch-modules-xen", and "openvswitch-debuginfo".
  46
  47 Installing Open vSwitch for XenServer
  48 -------------------------------------
  49
  50 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
  51 copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
  52 "scp", then install them with "rpm -U", e.g.:
  53
  54      scp openvswitch-$VERSION-1.i386.rpm \
  55          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
  56          root@<host>:
  57 (At this point you will have to enter <host>'s root password.)
  58      ssh root@<host>
  59 (At this point you will have to enter <host>'s root password again.)
  60      rpm -U openvswitch-$VERSION-1.i386.rpm \
  61          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
  62
  63 To uninstall Open vSwitch from a XenServer host, remove the packages:
  64
  65      ssh root@<host>
  66 (At this point you will have to enter <host>'s root password again.)
  67      rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
  68
  69 After installing or uninstalling Open vSwitch, the XenServer should be
  70 rebooted as soon as possible.
  71
  72 Open vSwitch Boot Sequence on XenServer
  73 ---------------------------------------
  74
  75 When Open vSwitch is installed on XenServer, its startup script
  76 /etc/init.d/openvswitch runs early in boot.  It does roughly the
  77 following:
  78
  79         * Loads the OVS kernel module, openvswitch_mod.
  80
  81         * Starts ovsdb-server, the OVS configuration database.
  82
  83         * XenServer expects there to be no bridges configured at
  84           startup, but the OVS configuration database likely still has
  85           bridges configured from before reboot.  To match XenServer
  86           expectations, the startup script deletes all configured
  87           bridges from the database.
  88
  89         * Starts ovs-vswitchd, the OVS switching daemon.
  90
  91 At this point in the boot process, then, there are no Open vSwitch
  92 bridges, even though all of the Open vSwitch daemons are running.
  93 Later on in boot, /etc/init.d/management-interface (part of XenServer,
  94 not Open vSwitch) creates the bridge for the XAPI management interface
  95 by invoking /opt/xensource/libexec/interface-reconfigure.  Normally
  96 this program consults XAPI's database to obtain information about how
  97 to configure the bridge, but XAPI is not running yet[*] so it instead
  98 consults /var/xapi/network.dbcache, which is a cached copy of the most
  99 recent network configuration.
 100
 101 [*] Even if XAPI were running, if this XenServer node is a pool slave
 102     then the query would have to consult the master, which requires
 103     network access, which begs the question of how to configure the
 104     management interface.
 105
 106 XAPI starts later on in the boot process.  XAPI can then create other
 107 bridges on demand using /opt/xensource/libexec/interface-reconfigure.
 108 Now that XAPI is running, that program consults XAPI directly instead
 109 of reading the cache.
 110
 111 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
 112 script /etc/xapi.d/openvswitch-cfg-update passing the "update"
 113 command.  The plugin script does roughly the following:
 114
 115         * Calls /opt/xensource/libexec/interface-reconfigure with the
 116           "rewrite" command, to ensure that the network cache is
 117           up-to-date.
 118
 119         * Queries the Open vSwitch manager setting (named
 120           "vswitch_controller") from the XAPI database for the
 121           XenServer pool.
 122
 123         * If XAPI and OVS are configured for different managers, or if
 124           OVS is configured for a manager but XAPI is not, runs
 125           "ovs-vsctl emer-reset" to bring the Open vSwitch
 126           configuration to a known state.  One effect of emer-reset is
 127           to deconfigure any manager from the OVS database.
 128
 129         * If XAPI is configured for a manger, configures the OVS
 130           manager to match with "ovs-vsctl set-manager".
 131
 132 The Open vSwitch boot sequence only configures an OVS configuration
 133 database manager.  There is no way to directly configure an OpenFlow
 134 controller on XenServer and, as a consequence of the step above that
 135 deletes all of the bridges at boot time, controller configuration only
 136 persists until XenServer reboot.  The configuration database manager
 137 can, however, configure controllers for bridges.  See the BUGS section
 138 of ovs-controller(8) for more information on this topic.
 139
 140 Reporting Bugs
 141 --------------
 142
 143 Please report problems to bugs@openvswitch.org.