1 How to Install Open vSwitch on Citrix XenServer
2 ===============================================
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 instead.
8 These instructions have been tested with XenServer 5.6 FP1.
10 Building Open vSwitch for XenServer
11 -----------------------------------
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.
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 as prerequisites for
23 building from a Git tree.
25 2. Copy the distribution tarball into /usr/src/redhat/SOURCES inside
28 3. In the DDK VM, unpack the distribution tarball into a temporary
29 directory and "cd" into the root of the distribution tarball.
31 4. To build Open vSwitch userspace, run:
33 rpmbuild -bb xenserver/openvswitch-xen.spec
35 This produces three RPMs in /usr/src/redhat/RPMS/i386:
36 "openvswitch", "openvswitch-modules-xen", and
37 "openvswitch-debuginfo".
39 The above command automatically runs the Open vSwitch unit tests.
40 To disable the unit tests, run:
42 rpmbuild -bb --without check xenserver/openvswitch-xen.spec
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:
53 VERSION=<Open vSwitch version>
54 KERNEL_NAME=<Xen Kernel name>
55 KERNEL_VERSION=<Xen Kernel version>
56 KERNEL_FLAVOR=<Xen Kernel flavor(suffix) >
58 -D "openvswitch_version $VERSION" \
59 -D "kernel_name $KERNEL_NAME" \
60 -D "kernel_version $KERNEL_VERSION" \
61 -D "kernel_flavor $KERNEL_FLAVOR" \
62 -bb xenserver/openvswitch-xen.spec
66 <openvswitch version> is the version number that appears in the
67 name of the Open vSwitch tarball, e.g. 0.90.0.
69 <Xen Kernel name> is the name of the XenServer kernel package,
70 e.g. kernel-xen or kernel-NAME-xen, without the "kernel-" prefix.
72 <Xen Kernel version> is the output of:
73 rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>,
74 e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596, where <kernel-devel-package> is
75 the name of the -devel package corresponding to <Xen Kernel name>.
77 <Xen Kernel flavor (suffix) > is either "xen" or "kdump".
78 The "xen" flavor is the main running kernel flavor and the "kdump" flavor is
79 the crashdump kernel flavor. Commonly, one would specify "xen" here.
81 For XenServer 6.5 or above, the kernel version naming no longer contains
82 KERNEL_FLAVOR. Correspondingly, the the final "rpmbuild" step changes to:
85 VERSION=<Open vSwitch version>
86 KERNEL_NAME=<Xen Kernel name>
87 KERNEL_VERSION=<Xen Kernel version>
88 XEN_VERSION=<Xen Kernel flavor(suffix) >
90 -D "openvswitch_version $VERSION" \
91 -D "kernel_name $KERNEL_NAME" \
92 -D "kernel_version $KERNEL_VERSION" \
93 -D "xen_version $XEN_VERSION" \
94 -bb xenserver/openvswitch-xen.spec
99 `<Xen Version>` is the output of `uname -r`. Since XenServer 6.5, the
100 directory name in 'lib/modules/' becomes a shortened expression of the
103 Installing Open vSwitch for XenServer
104 -------------------------------------
106 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
107 copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
108 "scp", then install them with "rpm -U", e.g.:
110 scp openvswitch-$VERSION-1.i386.rpm \
111 openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
113 (At this point you will have to enter <host>'s root password.)
115 (At this point you will have to enter <host>'s root password again.)
116 rpm -U openvswitch-$VERSION-1.i386.rpm \
117 openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
119 To uninstall Open vSwitch from a XenServer host, remove the packages:
122 (At this point you will have to enter <host>'s root password again.)
123 rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
125 After installing or uninstalling Open vSwitch, the XenServer should be
126 rebooted as soon as possible.
128 Open vSwitch Boot Sequence on XenServer
129 ---------------------------------------
131 When Open vSwitch is installed on XenServer, its startup script
132 /etc/init.d/openvswitch runs early in boot. It does roughly the
135 * Loads the OVS kernel module, openvswitch.
137 * Starts ovsdb-server, the OVS configuration database.
139 * XenServer expects there to be no bridges configured at
140 startup, but the OVS configuration database likely still has
141 bridges configured from before reboot. To match XenServer
142 expectations, the startup script deletes all configured
143 bridges from the database.
145 * Starts ovs-vswitchd, the OVS switching daemon.
147 At this point in the boot process, then, there are no Open vSwitch
148 bridges, even though all of the Open vSwitch daemons are running.
149 Later on in boot, /etc/init.d/management-interface (part of XenServer,
150 not Open vSwitch) creates the bridge for the XAPI management interface
151 by invoking /opt/xensource/libexec/interface-reconfigure. Normally
152 this program consults XAPI's database to obtain information about how
153 to configure the bridge, but XAPI is not running yet[*] so it instead
154 consults /var/xapi/network.dbcache, which is a cached copy of the most
155 recent network configuration.
157 [*] Even if XAPI were running, if this XenServer node is a pool slave
158 then the query would have to consult the master, which requires
159 network access, which begs the question of how to configure the
160 management interface.
162 XAPI starts later on in the boot process. XAPI can then create other
163 bridges on demand using /opt/xensource/libexec/interface-reconfigure.
164 Now that XAPI is running, that program consults XAPI directly instead
165 of reading the cache.
167 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
168 script /etc/xapi.d/openvswitch-cfg-update passing the "update"
169 command. The plugin script does roughly the following:
171 * Calls /opt/xensource/libexec/interface-reconfigure with the
172 "rewrite" command, to ensure that the network cache is
175 * Queries the Open vSwitch manager setting (named
176 "vswitch_controller") from the XAPI database for the
179 * If XAPI and OVS are configured for different managers, or if
180 OVS is configured for a manager but XAPI is not, runs
181 "ovs-vsctl emer-reset" to bring the Open vSwitch
182 configuration to a known state. One effect of emer-reset is
183 to deconfigure any manager from the OVS database.
185 * If XAPI is configured for a manager, configures the OVS
186 manager to match with "ovs-vsctl set-manager".
191 * The Open vSwitch boot sequence only configures an OVS configuration
192 database manager. There is no way to directly configure an OpenFlow
193 controller on XenServer and, as a consequence of the step above that
194 deletes all of the bridges at boot time, controller configuration only
195 persists until XenServer reboot. The configuration database manager
196 can, however, configure controllers for bridges. See the BUGS section
197 of test-controller(8) for more information on this topic.
199 * The Open vSwitch startup script automatically adds a firewall rule
200 to allow GRE traffic. This rule is needed for the XenServer feature
201 called "Cross-Host Internal Networks" (CHIN) that uses GRE. If a user
202 configures tunnels other than GRE (ex: VXLAN, LISP), they will have
203 to either manually add a iptables firewall rule to allow the tunnel traffic
204 or add it through a startup script (Please refer to the "enable-protocol"
205 command in the ovs-ctl(8) manpage).
210 Please report problems to bugs@openvswitch.org.