xenserver: modify module spec file

[ovs.git] / INSTALL.XenServer

           How to Install Open vSwitch on Citrix XenServer
           ===============================================

This document describes how to build and install Open vSwitch on a
Citrix XenServer host.  If you want to install Open vSwitch on a
generic Linux host, see INSTALL.Linux instead.

These instructions have been tested with XenServer 5.6 FP1.

Building Open vSwitch for XenServer
-----------------------------------

The recommended build environment to build RPMs for Citrix XenServer
is the DDK VM available from Citrix.  If you are building from an Open
vSwitch distribution tarball, this VM has all the tools that you will
need.  If you are building from an Open vSwitch Git tree, then you
will need to first create a distribution tarball elsewhere, by running
"./boot.sh; ./configure; make dist" in the Git tree, because the DDK
VM does not include Autoconf or Automake that are required to
bootstrap the Open vSwitch distribution.

Once you have a distribution tarball, copy it into
/usr/src/redhat/SOURCES inside the VM.  Then execute the following:

   VERSION=<Open vSwitch version>
   KERNEL_NAME=<Xen Kernel name>
   KERNEL_VERSION=<Xen Kernel version>
   KERNEL_FLAVOR=<Xen Kernel flavor(suffix) >
   cd /tmp
   tar xfz /usr/src/redhat/SOURCES/openvswitch-$VERSION.tar.gz
   rpmbuild \
        -D "openvswitch_version $VERSION" \
        -D "kernel_name $KERNEL_NAME" \
        -D "kernel_version $KERNEL_VERSION" \
        -D "kernel_flavor $KERNEL_FLAVOR" \
        -bb openvswitch-$VERSION/xenserver/openvswitch-xen.spec

where:

    <openvswitch version> is the version number that appears in the
    name of the Open vSwitch tarball, e.g. 0.90.0.

    <Xen Kernel name> is the name of the Xen Kernel,
    e.g. kernel-xen or kernel-NAME-xen. By convention, the name
    starts with "kernel-" and ends with "-xen".
    This can be obtained by executing 
        'rpm -q --queryformat "%{Name}" kernel.*xen'
    with the "kernel-" stripped out using  sed 's/kernel-//'
    e.g. kernel-NAME-xen => NAME-xen

    <Xen Kernel version> is the output of:
    rpm -q --queryformat "%{Version}-%{Release}" kernel.*xen-devel
    e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596

    <Xen Kernel flavor (suffix) > is either "xen" or "kdump".
    The "xen" flavor is the main running kernel flavor and the "kdump" flavor is
    the crashdump kernel flavor. Commonly, one would specify "xen" here.

Three RPMs will be output into /usr/src/redhat/RPMS/i386, whose names begin
with "openvswitch", "openvswitch-modules-xen" (if building for kernel_flavor=xen),
and "openvswitch-debuginfo".

Installing Open vSwitch for XenServer
-------------------------------------

To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
"scp", then install them with "rpm -U", e.g.:

     scp openvswitch-$VERSION-1.i386.rpm \
         openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
         root@<host>:
(At this point you will have to enter <host>'s root password.)
     ssh root@<host>
(At this point you will have to enter <host>'s root password again.)
     rpm -U openvswitch-$VERSION-1.i386.rpm \
         openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm

To uninstall Open vSwitch from a XenServer host, remove the packages:

     ssh root@<host>
(At this point you will have to enter <host>'s root password again.)
     rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION

After installing or uninstalling Open vSwitch, the XenServer should be
rebooted as soon as possible.

Open vSwitch Boot Sequence on XenServer
---------------------------------------

When Open vSwitch is installed on XenServer, its startup script
/etc/init.d/openvswitch runs early in boot.  It does roughly the
following:

        * Loads the OVS kernel module, openvswitch_mod.

        * Starts ovsdb-server, the OVS configuration database.

        * XenServer expects there to be no bridges configured at
          startup, but the OVS configuration database likely still has
          bridges configured from before reboot.  To match XenServer
          expectations, the startup script deletes all configured
          bridges from the database.

        * Starts ovs-vswitchd, the OVS switching daemon.

At this point in the boot process, then, there are no Open vSwitch
bridges, even though all of the Open vSwitch daemons are running.
Later on in boot, /etc/init.d/management-interface (part of XenServer,
not Open vSwitch) creates the bridge for the XAPI management interface
by invoking /opt/xensource/libexec/interface-reconfigure.  Normally
this program consults XAPI's database to obtain information about how
to configure the bridge, but XAPI is not running yet[*] so it instead
consults /var/xapi/network.dbcache, which is a cached copy of the most
recent network configuration.

[*] Even if XAPI were running, if this XenServer node is a pool slave
    then the query would have to consult the master, which requires
    network access, which begs the question of how to configure the
    management interface.

XAPI starts later on in the boot process.  XAPI can then create other
bridges on demand using /opt/xensource/libexec/interface-reconfigure.
Now that XAPI is running, that program consults XAPI directly instead
of reading the cache.

As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
script /etc/xapi.d/openvswitch-cfg-update passing the "update"
command.  The plugin script does roughly the following:

        * Calls /opt/xensource/libexec/interface-reconfigure with the
          "rewrite" command, to ensure that the network cache is
          up-to-date.

        * Queries the Open vSwitch manager setting (named
          "vswitch_controller") from the XAPI database for the
          XenServer pool.

        * If XAPI and OVS are configured for different managers, or if
          OVS is configured for a manager but XAPI is not, runs
          "ovs-vsctl emer-reset" to bring the Open vSwitch
          configuration to a known state.  One effect of emer-reset is
          to deconfigure any manager from the OVS database.

        * If XAPI is configured for a manger, configures the OVS
          manager to match with "ovs-vsctl set-manager".

The Open vSwitch boot sequence only configures an OVS configuration
database manager.  There is no way to directly configure an OpenFlow
controller on XenServer and, as a consequence of the step above that
deletes all of the bridges at boot time, controller configuration only
persists until XenServer reboot.  The configuration database manager
can, however, configure controllers for bridges.  See the BUGS section
of ovs-controller(8) for more information on this topic.

Reporting Bugs
--------------

Please report problems to bugs@openvswitch.org.