]>
Commit | Line | Data |
---|---|---|
716b9b44 SF |
1 | .. |
2 | Licensed under the Apache License, Version 2.0 (the "License"); you may | |
3 | not use this file except in compliance with the License. You may obtain | |
4 | a copy of the License at | |
5 | ||
6 | http://www.apache.org/licenses/LICENSE-2.0 | |
7 | ||
8 | Unless required by applicable law or agreed to in writing, software | |
9 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
10 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
11 | License for the specific language governing permissions and limitations | |
12 | under the License. | |
13 | ||
14 | Convention for heading levels in Open vSwitch documentation: | |
15 | ||
16 | ======= Heading 0 (reserved for the title in a document) | |
17 | ------- Heading 1 | |
18 | ~~~~~~~ Heading 2 | |
19 | +++++++ Heading 3 | |
20 | ''''''' Heading 4 | |
21 | ||
22 | Avoid deeper levels because they do not render well. | |
23 | ||
24 | =============================================== | |
25 | How to Install Open vSwitch on Citrix XenServer | |
26 | =============================================== | |
27 | ||
28 | This document describes how to build and install Open vSwitch on a Citrix | |
29 | XenServer host. If you want to install Open vSwitch on a generic Linux or BSD | |
30 | host, see the `installation guide <INSTALL.rst>`__ instead. | |
31 | ||
32 | Open vSwitch should work with XenServer 5.6.100 and later. However, Open | |
33 | vSwitch requires Python 2.7 or later, so using Open vSwitch with XenServer 6.5 | |
34 | or earlier requires installing Python 2.7. | |
35 | ||
36 | Building | |
37 | -------- | |
38 | ||
39 | You may build from an Open vSwitch distribution tarball or from an Open vSwitch | |
40 | Git tree. The recommended build environment to build RPMs for Citrix XenServer | |
41 | is the DDK VM available from Citrix. | |
42 | ||
43 | 1. If you are building from an Open vSwitch Git tree, then you will need to | |
dc76953f | 44 | first create a distribution tarball by running:: |
716b9b44 SF |
45 | |
46 | $ ./boot.sh | |
47 | $ ./configure | |
48 | $ make dist | |
49 | ||
50 | You cannot run this in the DDK VM, because it lacks tools that are necessary | |
51 | to bootstrap the Open vSwitch distribution. Instead, you must run this on a | |
52 | machine that has the tools listed in the installation guide <INSTALL.rst>`__ | |
53 | as prerequisites for building from a Git tree. | |
54 | ||
55 | 2. Copy the distribution tarball into ``/usr/src/redhat/SOURCES`` inside | |
56 | the DDK VM. | |
57 | ||
58 | 3. In the DDK VM, unpack the distribution tarball into a temporary directory | |
59 | and "cd" into the root of the distribution tarball. | |
60 | ||
dc76953f | 61 | 4. To build Open vSwitch userspace, run:: |
716b9b44 SF |
62 | |
63 | $ rpmbuild -bb xenserver/openvswitch-xen.spec | |
64 | ||
65 | This produces three RPMs in ``/usr/src/redhat/RPMS/i386``: | |
66 | ||
67 | - ``openvswitch`` | |
68 | - ``openvswitch-modules-xen`` | |
69 | - ``openvswitch-debuginfo`` | |
70 | ||
71 | The above command automatically runs the Open vSwitch unit tests. To | |
dc76953f | 72 | disable the unit tests, run:: |
716b9b44 SF |
73 | |
74 | $ rpmbuild -bb --without check xenserver/openvswitch-xen.spec | |
75 | ||
76 | Build Parameters | |
77 | ---------------- | |
78 | ||
79 | ``openvswitch-xen.spec`` needs to know a number of pieces of information about | |
80 | the XenServer kernel. Usually, it can figure these out for itself, but if it | |
81 | does not do it correctly then you can specify them yourself as parameters to | |
dc76953f | 82 | the build. Thus, the final ``rpmbuild`` step above can be elaborated as:: |
716b9b44 SF |
83 | |
84 | $ VERSION=<Open vSwitch version> | |
85 | $ KERNEL_NAME=<Xen Kernel name> | |
86 | $ KERNEL_VERSION=<Xen Kernel version> | |
87 | $ KERNEL_FLAVOR=<Xen Kernel flavor(suffix)> | |
88 | $ rpmbuild \ | |
89 | -D "openvswitch_version $VERSION" \ | |
90 | -D "kernel_name $KERNEL_NAME" \ | |
91 | -D "kernel_version $KERNEL_VERSION" \ | |
92 | -D "kernel_flavor $KERNEL_FLAVOR" \ | |
93 | -bb xenserver/openvswitch-xen.spec | |
94 | ||
95 | where: | |
96 | ||
97 | ``<openvswitch version>`` | |
98 | is the version number that appears in the name of the Open vSwitch tarball, | |
99 | e.g. 0.90.0. | |
100 | ||
101 | ``<Xen Kernel name>`` | |
102 | is the name of the XenServer kernel package, e.g. ``kernel-xen`` or | |
103 | ``kernel-NAME-xen``, without the ``kernel-`` prefix. | |
104 | ||
105 | ``<Xen Kernel version>`` | |
dc76953f | 106 | is the output of:: |
716b9b44 SF |
107 | |
108 | $ rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>, | |
109 | ||
110 | e.g. ``2.6.32.12-0.7.1.xs5.6.100.323.170596``, where | |
111 | ``<kernel-devel-package>`` is the name of the ``-devel`` package | |
112 | corresponding to ``<Xen Kernel name>``. | |
113 | ||
114 | ``<Xen Kernel flavor (suffix)>`` | |
115 | is either ``xen`` or ``kdump``, where ``xen`` flavor is the main running | |
116 | kernel flavor and the ``kdump`` flavor is the crashdump kernel flavor. | |
117 | Commonly, one would specify ``xen`` here. | |
118 | ||
119 | For XenServer 6.5 or above, the kernel version naming no longer contains | |
120 | KERNEL_FLAVOR. In fact, only providing the ``uname -r`` output is enough. So, | |
dc76953f | 121 | the final ``rpmbuild`` step changes to:: |
716b9b44 SF |
122 | |
123 | $ KERNEL_UNAME=<`uname -r` output> | |
124 | $ rpmbuild \ | |
125 | -D "kenel_uname $KERNEL_UNAME" \ | |
126 | -bb xenserver/openvswitch-xen.spec | |
127 | ||
128 | Installing Open vSwitch for XenServer | |
129 | ------------------------------------- | |
130 | ||
131 | To install Open vSwitch on a XenServer host, or to upgrade to a newer version, | |
132 | copy the ``openvswitch`` and ``openvswitch-modules-xen`` RPMs to that host with | |
dc76953f | 133 | ``scp``, then install them with ``rpm -U``, e.g.:: |
716b9b44 SF |
134 | |
135 | $ scp openvswitch-$VERSION-1.i386.rpm \ | |
136 | openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \ | |
137 | root@<host>: | |
138 | # Enter <host>'s root password. | |
139 | $ ssh root@<host> | |
140 | # Enter <host>'s root password again. | |
141 | $ rpm -U openvswitch-$VERSION-1.i386.rpm \ | |
142 | openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm | |
143 | ||
dc76953f | 144 | To uninstall Open vSwitch from a XenServer host, remove the packages:: |
716b9b44 SF |
145 | |
146 | $ ssh root@<host> | |
147 | # Enter <host>'s root password again. | |
148 | $ rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION | |
149 | ||
150 | After installing or uninstalling Open vSwitch, the XenServer should be rebooted | |
151 | as soon as possible. | |
152 | ||
153 | Open vSwitch Boot Sequence on XenServer | |
154 | --------------------------------------- | |
155 | ||
156 | When Open vSwitch is installed on XenServer, its startup script | |
157 | ``/etc/init.d/openvswitch`` runs early in boot. It does roughly the following: | |
158 | ||
159 | * Loads the OVS kernel module, openvswitch. | |
160 | ||
161 | * Starts ovsdb-server, the OVS configuration database. | |
162 | ||
163 | * XenServer expects there to be no bridges configured at startup, but the OVS | |
164 | configuration database likely still has bridges configured from before | |
165 | reboot. To match XenServer expectations, the startup script deletes all | |
166 | configured bridges from the database. | |
167 | ||
168 | * Starts ovs-vswitchd, the OVS switching daemon. | |
169 | ||
170 | At this point in the boot process, then, there are no Open vSwitch bridges, | |
171 | even though all of the Open vSwitch daemons are running. Later on in boot, | |
172 | ``/etc/init.d/management-interface`` (part of XenServer, not Open vSwitch) | |
173 | creates the bridge for the XAPI management interface by invoking | |
174 | ``/opt/xensource/libexec/interface-reconfigure``. Normally this program | |
175 | consults XAPI's database to obtain information about how to configure the | |
176 | bridge, but XAPI is not running yet(\*) so it instead consults | |
177 | ``/var/xapi/network.dbcache``, which is a cached copy of the most recent | |
178 | network configuration. | |
179 | ||
180 | (\*) Even if XAPI were running, if this XenServer node is a pool slave then the | |
181 | query would have to consult the master, which requires network access, | |
182 | which begs the question of how to configure the management interface. | |
183 | ||
184 | XAPI starts later on in the boot process. XAPI can then create other bridges | |
185 | on demand using ``/opt/xensource/libexec/interface-reconfigure``. Now that | |
186 | XAPI is running, that program consults XAPI directly instead of reading the | |
187 | cache. | |
188 | ||
189 | As part of its own startup, XAPI invokes the Open vSwitch XAPI plugin script | |
190 | ``/etc/xapi.d/openvswitch-cfg-update`` passing the ``update`` command. The | |
191 | plugin script does roughly the following: | |
192 | ||
193 | * Calls ``/opt/xensource/libexec/interface-reconfigure`` with the ``rewrite`` | |
194 | command, to ensure that the network cache is up-to-date. | |
195 | ||
196 | * Queries the Open vSwitch manager setting (named ``vswitch_controller``) from | |
197 | the XAPI database for the XenServer pool. | |
198 | ||
199 | * If XAPI and OVS are configured for different managers, or if OVS is | |
200 | configured for a manager but XAPI is not, runs ``ovs-vsctl emer-reset`` to | |
201 | bring the Open vSwitch configuration to a known state. One effect of | |
202 | emer-reset is to deconfigure any manager from the OVS database. | |
203 | ||
204 | * If XAPI is configured for a manager, configures the OVS manager to match with | |
205 | ``ovs-vsctl set-manager``. | |
206 | ||
207 | Notes | |
208 | ----- | |
209 | ||
210 | * The Open vSwitch boot sequence only configures an OVS configuration database | |
211 | manager. There is no way to directly configure an OpenFlow controller on | |
212 | XenServer and, as a consequence of the step above that deletes all of the | |
213 | bridges at boot time, controller configuration only persists until XenServer | |
214 | reboot. The configuration database manager can, however, configure | |
215 | controllers for bridges. See the BUGS section of ovs-testcontroller(8) for | |
216 | more information on this topic. | |
217 | ||
218 | * The Open vSwitch startup script automatically adds a firewall rule to allow | |
219 | GRE traffic. This rule is needed for the XenServer feature called "Cross-Host | |
220 | Internal Networks" (CHIN) that uses GRE. If a user configures tunnels other | |
221 | than GRE (ex: Geneve, VXLAN, LISP), they will have to either manually add a | |
222 | iptables firewall rule to allow the tunnel traffic or add it through a | |
223 | startup script (Please refer to the "enable-protocol" command in the | |
224 | ovs-ctl(8) manpage). | |
225 | ||
226 | Reporting Bugs | |
227 | -------------- | |
228 | ||
229 | Please report problems to bugs@openvswitch.org. |