datapath: Remove unused vlan constants.
[sliver-openvswitch.git] / 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    KERNEL_NAME=<Xen Kernel name>
27    KERNEL_VERSION=<Xen Kernel version>
28    KERNEL_FLAVOR=<Xen Kernel flavor(suffix) >
29    cd /tmp
30    tar xfz /usr/src/redhat/SOURCES/openvswitch-$VERSION.tar.gz
31    rpmbuild \
32         -D "openvswitch_version $VERSION" \
33         -D "kernel_name $KERNEL_NAME" \
34         -D "kernel_version $KERNEL_VERSION" \
35         -D "kernel_flavor $KERNEL_FLAVOR" \
36         -bb openvswitch-$VERSION/xenserver/openvswitch-xen.spec
37
38 where:
39
40     <openvswitch version> is the version number that appears in the
41     name of the Open vSwitch tarball, e.g. 0.90.0.
42
43     <Xen Kernel name> is the name of the Xen Kernel,
44     e.g. kernel-xen or kernel-NAME-xen. By convention, the name
45     starts with "kernel-" and ends with "-xen".
46     This can be obtained by executing 
47         'rpm -q --queryformat "%{Name}" kernel.*xen'
48     with the "kernel-" stripped out using  sed 's/kernel-//'
49     e.g. kernel-NAME-xen => NAME-xen
50
51     <Xen Kernel version> is the output of:
52     rpm -q --queryformat "%{Version}-%{Release}" kernel.*xen-devel
53     e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596
54
55     <Xen Kernel flavor (suffix) > is either "xen" or "kdump".
56     The "xen" flavor is the main running kernel flavor and the "kdump" flavor is
57     the crashdump kernel flavor. Commonly, one would specify "xen" here.
58
59 Three RPMs will be output into /usr/src/redhat/RPMS/i386, whose names begin
60 with "openvswitch", "openvswitch-modules-xen" (if building for kernel_flavor=xen),
61 and "openvswitch-debuginfo".
62
63 Installing Open vSwitch for XenServer
64 -------------------------------------
65
66 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
67 copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
68 "scp", then install them with "rpm -U", e.g.:
69
70      scp openvswitch-$VERSION-1.i386.rpm \
71          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
72          root@<host>:
73 (At this point you will have to enter <host>'s root password.)
74      ssh root@<host>
75 (At this point you will have to enter <host>'s root password again.)
76      rpm -U openvswitch-$VERSION-1.i386.rpm \
77          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
78
79 To uninstall Open vSwitch from a XenServer host, remove the packages:
80
81      ssh root@<host>
82 (At this point you will have to enter <host>'s root password again.)
83      rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
84
85 After installing or uninstalling Open vSwitch, the XenServer should be
86 rebooted as soon as possible.
87
88 Open vSwitch Boot Sequence on XenServer
89 ---------------------------------------
90
91 When Open vSwitch is installed on XenServer, its startup script
92 /etc/init.d/openvswitch runs early in boot.  It does roughly the
93 following:
94
95         * Loads the OVS kernel module, openvswitch_mod.
96
97         * Starts ovsdb-server, the OVS configuration database.
98
99         * XenServer expects there to be no bridges configured at
100           startup, but the OVS configuration database likely still has
101           bridges configured from before reboot.  To match XenServer
102           expectations, the startup script deletes all configured
103           bridges from the database.
104
105         * Starts ovs-vswitchd, the OVS switching daemon.
106
107 At this point in the boot process, then, there are no Open vSwitch
108 bridges, even though all of the Open vSwitch daemons are running.
109 Later on in boot, /etc/init.d/management-interface (part of XenServer,
110 not Open vSwitch) creates the bridge for the XAPI management interface
111 by invoking /opt/xensource/libexec/interface-reconfigure.  Normally
112 this program consults XAPI's database to obtain information about how
113 to configure the bridge, but XAPI is not running yet[*] so it instead
114 consults /var/xapi/network.dbcache, which is a cached copy of the most
115 recent network configuration.
116
117 [*] Even if XAPI were running, if this XenServer node is a pool slave
118     then the query would have to consult the master, which requires
119     network access, which begs the question of how to configure the
120     management interface.
121
122 XAPI starts later on in the boot process.  XAPI can then create other
123 bridges on demand using /opt/xensource/libexec/interface-reconfigure.
124 Now that XAPI is running, that program consults XAPI directly instead
125 of reading the cache.
126
127 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
128 script /etc/xapi.d/openvswitch-cfg-update passing the "update"
129 command.  The plugin script does roughly the following:
130
131         * Calls /opt/xensource/libexec/interface-reconfigure with the
132           "rewrite" command, to ensure that the network cache is
133           up-to-date.
134
135         * Queries the Open vSwitch manager setting (named
136           "vswitch_controller") from the XAPI database for the
137           XenServer pool.
138
139         * If XAPI and OVS are configured for different managers, or if
140           OVS is configured for a manager but XAPI is not, runs
141           "ovs-vsctl emer-reset" to bring the Open vSwitch
142           configuration to a known state.  One effect of emer-reset is
143           to deconfigure any manager from the OVS database.
144
145         * If XAPI is configured for a manger, configures the OVS
146           manager to match with "ovs-vsctl set-manager".
147
148 The Open vSwitch boot sequence only configures an OVS configuration
149 database manager.  There is no way to directly configure an OpenFlow
150 controller on XenServer and, as a consequence of the step above that
151 deletes all of the bridges at boot time, controller configuration only
152 persists until XenServer reboot.  The configuration database manager
153 can, however, configure controllers for bridges.  See the BUGS section
154 of ovs-controller(8) for more information on this topic.
155
156 Reporting Bugs
157 --------------
158
159 Please report problems to bugs@openvswitch.org.