some ctype related casts to suppress gcc warnings on NetBSD
[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 or BSD host, see INSTALL 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 as prerequisites for
23    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 Build Parameters
40 ----------------
41
42 openvswitch-xen.spec needs to know a number of pieces of information
43 about the XenServer kernel.  Usually, it can figure these out for
44 itself, but if it does not do it correctly then you can specify them
45 yourself as parameters to the build.  Thus, the final "rpmbuild" step
46 above can be elaborated as:
47
48    VERSION=<Open vSwitch version>
49    KERNEL_NAME=<Xen Kernel name>
50    KERNEL_VERSION=<Xen Kernel version>
51    KERNEL_FLAVOR=<Xen Kernel flavor(suffix) >
52    rpmbuild \
53         -D "openvswitch_version $VERSION" \
54         -D "kernel_name $KERNEL_NAME" \
55         -D "kernel_version $KERNEL_VERSION" \
56         -D "kernel_flavor $KERNEL_FLAVOR" \
57         -bb xenserver/openvswitch-xen.spec
58
59 where:
60
61     <openvswitch version> is the version number that appears in the
62     name of the Open vSwitch tarball, e.g. 0.90.0.
63
64     <Xen Kernel name> is the name of the XenServer kernel package,
65     e.g. kernel-xen or kernel-NAME-xen, without the "kernel-" prefix.
66
67     <Xen Kernel version> is the output of:
68     rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>,
69     e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596, where <kernel-devel-package> is
70     the name of the -devel package corresponding to <Xen Kernel name>.
71
72     <Xen Kernel flavor (suffix) > is either "xen" or "kdump".
73     The "xen" flavor is the main running kernel flavor and the "kdump" flavor is
74     the crashdump kernel flavor. Commonly, one would specify "xen" here.
75
76 Installing Open vSwitch for XenServer
77 -------------------------------------
78
79 To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
80 copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
81 "scp", then install them with "rpm -U", e.g.:
82
83      scp openvswitch-$VERSION-1.i386.rpm \
84          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
85          root@<host>:
86 (At this point you will have to enter <host>'s root password.)
87      ssh root@<host>
88 (At this point you will have to enter <host>'s root password again.)
89      rpm -U openvswitch-$VERSION-1.i386.rpm \
90          openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
91
92 To uninstall Open vSwitch from a XenServer host, remove the packages:
93
94      ssh root@<host>
95 (At this point you will have to enter <host>'s root password again.)
96      rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
97
98 After installing or uninstalling Open vSwitch, the XenServer should be
99 rebooted as soon as possible.
100
101 Open vSwitch Boot Sequence on XenServer
102 ---------------------------------------
103
104 When Open vSwitch is installed on XenServer, its startup script
105 /etc/init.d/openvswitch runs early in boot.  It does roughly the
106 following:
107
108         * Loads the OVS kernel module, openvswitch.
109
110         * Starts ovsdb-server, the OVS configuration database.
111
112         * XenServer expects there to be no bridges configured at
113           startup, but the OVS configuration database likely still has
114           bridges configured from before reboot.  To match XenServer
115           expectations, the startup script deletes all configured
116           bridges from the database.
117
118         * Starts ovs-vswitchd, the OVS switching daemon.
119
120 At this point in the boot process, then, there are no Open vSwitch
121 bridges, even though all of the Open vSwitch daemons are running.
122 Later on in boot, /etc/init.d/management-interface (part of XenServer,
123 not Open vSwitch) creates the bridge for the XAPI management interface
124 by invoking /opt/xensource/libexec/interface-reconfigure.  Normally
125 this program consults XAPI's database to obtain information about how
126 to configure the bridge, but XAPI is not running yet[*] so it instead
127 consults /var/xapi/network.dbcache, which is a cached copy of the most
128 recent network configuration.
129
130 [*] Even if XAPI were running, if this XenServer node is a pool slave
131     then the query would have to consult the master, which requires
132     network access, which begs the question of how to configure the
133     management interface.
134
135 XAPI starts later on in the boot process.  XAPI can then create other
136 bridges on demand using /opt/xensource/libexec/interface-reconfigure.
137 Now that XAPI is running, that program consults XAPI directly instead
138 of reading the cache.
139
140 As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin
141 script /etc/xapi.d/openvswitch-cfg-update passing the "update"
142 command.  The plugin script does roughly the following:
143
144         * Calls /opt/xensource/libexec/interface-reconfigure with the
145           "rewrite" command, to ensure that the network cache is
146           up-to-date.
147
148         * Queries the Open vSwitch manager setting (named
149           "vswitch_controller") from the XAPI database for the
150           XenServer pool.
151
152         * If XAPI and OVS are configured for different managers, or if
153           OVS is configured for a manager but XAPI is not, runs
154           "ovs-vsctl emer-reset" to bring the Open vSwitch
155           configuration to a known state.  One effect of emer-reset is
156           to deconfigure any manager from the OVS database.
157
158         * If XAPI is configured for a manager, configures the OVS
159           manager to match with "ovs-vsctl set-manager".
160
161 Notes
162 -----
163
164 * The Open vSwitch boot sequence only configures an OVS configuration
165 database manager.  There is no way to directly configure an OpenFlow
166 controller on XenServer and, as a consequence of the step above that
167 deletes all of the bridges at boot time, controller configuration only
168 persists until XenServer reboot.  The configuration database manager
169 can, however, configure controllers for bridges.  See the BUGS section
170 of ovs-controller(8) for more information on this topic.
171
172 * The Open vSwitch startup script automatically adds a firewall rule
173 to allow GRE traffic. This rule is needed for the XenServer feature
174 called "Cross-Host Internal Networks" (CHIN) that uses GRE. If a user
175 configures tunnels other than GRE (ex: VXLAN, LISP), they will have
176 to either manually add a iptables firewall rule to allow the tunnel traffic
177 or add it through a startup script (Please refer to the "enable-protocol"
178 command in the ovs-ctl(8) manpage).
179
180 Reporting Bugs
181 --------------
182
183 Please report problems to bugs@openvswitch.org.