1 | How to Install Open vSwitch on Linux
|
---|
2 | ====================================
|
---|
3 |
|
---|
4 | This document describes how to build and install Open vSwitch on a
|
---|
5 | generic Linux host. If you want to install Open vSwitch on a Citrix
|
---|
6 | XenServer, see INSTALL.XenServer instead.
|
---|
7 |
|
---|
8 | This version of Open vSwitch may be built manually with "configure"
|
---|
9 | and "make", as described below. You may also build Debian packages by
|
---|
10 | running "dpkg-buildpackage".
|
---|
11 |
|
---|
12 | Build Requirements
|
---|
13 | ------------------
|
---|
14 |
|
---|
15 | To compile the userspace programs in the Open vSwitch distribution,
|
---|
16 | you will need the following software:
|
---|
17 |
|
---|
18 | - A make program, e.g. GNU make. BSD make should also work.
|
---|
19 |
|
---|
20 | - The GNU C compiler. We generally test with version 4.1, 4.2, or
|
---|
21 | 4.3.
|
---|
22 |
|
---|
23 | - pkg-config. We test with version 0.22.
|
---|
24 |
|
---|
25 | - libssl, from OpenSSL, is optional but recommended if you plan to
|
---|
26 | connect the Open vSwitch to an OpenFlow controller. libssl is
|
---|
27 | required to establish confidentiality and authenticity in the
|
---|
28 | connections from an Open vSwitch to an OpenFlow controller. If
|
---|
29 | libssl is installed, then Open vSwitch will automatically build
|
---|
30 | with support for it.
|
---|
31 |
|
---|
32 | To compile the kernel module, you must also install the following. If
|
---|
33 | you cannot build or install the kernel module, you may use the
|
---|
34 | userspace-only implementation, at a cost in performance. The
|
---|
35 | userspace implementation may also lack some features. Refer to
|
---|
36 | INSTALL.userspace for more information.
|
---|
37 |
|
---|
38 | - A supported Linux kernel version. Please refer to README for a
|
---|
39 | list of supported versions.
|
---|
40 |
|
---|
41 | The Open vSwitch datapath requires bridging support
|
---|
42 | (CONFIG_BRIDGE) to be built as a kernel module. (This is common
|
---|
43 | in kernels provided by Linux distributions.) The bridge module
|
---|
44 | must not be loaded or in use. If the bridge module is running
|
---|
45 | (check with "lsmod | grep bridge"), you must remove it ("rmmod
|
---|
46 | bridge") before starting the datapath.
|
---|
47 |
|
---|
48 | For optional support of ingress policing, you must enable kernel
|
---|
49 | configuration options NET_CLS_ACT, NET_CLS_U32, NET_SCH_INGRESS,
|
---|
50 | and NET_ACT_POLICE, either built-in or as modules.
|
---|
51 | (NET_CLS_POLICE is obsolete and not needed.)
|
---|
52 |
|
---|
53 | If GRE tunneling is being used it is recommended that the kernel
|
---|
54 | be compiled with IPv6 support (CONFIG_IPV6). This allows for
|
---|
55 | special handling (such as path MTU discovery) of IPv6 packets.
|
---|
56 |
|
---|
57 | To configure HTB or HFSC quality of service with Open vSwitch,
|
---|
58 | you must enable the respective configuration options.
|
---|
59 |
|
---|
60 | To use Open vSwitch support for TAP devices, you must enable
|
---|
61 | CONFIG_TUN.
|
---|
62 |
|
---|
63 | - To build a kernel module, you need the same version of GCC that
|
---|
64 | was used to build that kernel.
|
---|
65 |
|
---|
66 | - A kernel build directory corresponding to the Linux kernel image
|
---|
67 | the module is to run on. Under Debian and Ubuntu, for example,
|
---|
68 | each linux-image package containing a kernel binary has a
|
---|
69 | corresponding linux-headers package with the required build
|
---|
70 | infrastructure.
|
---|
71 |
|
---|
72 | If you are working from a Git tree or snapshot (instead of from a
|
---|
73 | distribution tarball), or if you modify the Open vSwitch build system
|
---|
74 | or the database schema, you will also need the following software:
|
---|
75 |
|
---|
76 | - Autoconf version 2.64 or later.
|
---|
77 |
|
---|
78 | - Automake version 1.10 or later.
|
---|
79 |
|
---|
80 | - Python 2.x, for x >= 4.
|
---|
81 |
|
---|
82 | If you modify the ovsdbmonitor tool, then you will also need the
|
---|
83 | following:
|
---|
84 |
|
---|
85 | - pyuic4 from PyQt4 (http://www.riverbankcomputing.co.uk).
|
---|
86 |
|
---|
87 | To run the unit tests, you also need:
|
---|
88 |
|
---|
89 | - Perl. Version 5.10.1 is known to work. Earlier versions should
|
---|
90 | also work.
|
---|
91 |
|
---|
92 | If you modify the vswitchd database schema, then the E-R diagram in
|
---|
93 | the ovs-vswitchd.conf.db(5) manpage will be updated properly only if
|
---|
94 | you have the following:
|
---|
95 |
|
---|
96 | - "dot" from graphviz (http://www.graphviz.org/).
|
---|
97 |
|
---|
98 | - Perl. Version 5.10.1 is known to work. Earlier versions should
|
---|
99 | also work.
|
---|
100 |
|
---|
101 | - Python 2.x, for x >= 4.
|
---|
102 |
|
---|
103 | Installation Requirements
|
---|
104 | -------------------------
|
---|
105 |
|
---|
106 | The machine on which Open vSwitch is to be installed must have the
|
---|
107 | following software:
|
---|
108 |
|
---|
109 | - libc compatible with the libc used for build.
|
---|
110 |
|
---|
111 | - libssl compatible with the libssl used for build, if OpenSSL was
|
---|
112 | used for the build.
|
---|
113 |
|
---|
114 | - The Linux kernel version configured as part of the build.
|
---|
115 |
|
---|
116 | - For optional support of ingress policing, the "tc" program from
|
---|
117 | iproute2 (part of all major distributions and available at
|
---|
118 | http://www.linux-foundation.org/en/Net:Iproute2).
|
---|
119 |
|
---|
120 | - For debugging purposes, Open vSwitch expects that "tcpdump" is
|
---|
121 | installed as /usr/sbin/tcpdump. If tcpdump is not installed, or
|
---|
122 | if it is installed in a different location, then some Open
|
---|
123 | vSwitch log messages will not be as detailed.
|
---|
124 |
|
---|
125 | You should ensure that /dev/urandom exists. To support TAP devices,
|
---|
126 | you must also ensure that /dev/net/tun exists.
|
---|
127 |
|
---|
128 | To run the ovsdmonitor tool, the machine must also have the following
|
---|
129 | software:
|
---|
130 |
|
---|
131 | - Python 2.x, for x >= 4.
|
---|
132 |
|
---|
133 | - Python Twisted Conch.
|
---|
134 |
|
---|
135 | - Python JSON.
|
---|
136 |
|
---|
137 | - PySide or PyQt4.
|
---|
138 |
|
---|
139 | - Python Zope interface module.
|
---|
140 |
|
---|
141 | (On Debian "lenny" the above can be installed with "apt-get install
|
---|
142 | python-json python-qt4 python-zopeinterface python-twisted-conch".)
|
---|
143 |
|
---|
144 | Building and Installing Open vSwitch for Linux
|
---|
145 | ==============================================
|
---|
146 |
|
---|
147 | Once you have installed all the prerequisites listed above in the Base
|
---|
148 | Prerequisites section, follow the procedure below to build.
|
---|
149 |
|
---|
150 | 1. If you pulled the sources directly from an Open vSwitch Git tree,
|
---|
151 | run boot.sh in the top source directory:
|
---|
152 |
|
---|
153 | % ./boot.sh
|
---|
154 |
|
---|
155 | 2. In the top source directory, configure the package by running the
|
---|
156 | configure script. You can usually invoke configure without any
|
---|
157 | arguments:
|
---|
158 |
|
---|
159 | % ./configure
|
---|
160 |
|
---|
161 | By default all files are installed under /usr/local. If you want
|
---|
162 | to install into, e.g., /usr and /var instead of /usr/local and
|
---|
163 | /usr/local/var, add options as shown here:
|
---|
164 |
|
---|
165 | % ./configure --prefix=/usr --localstatedir=/var
|
---|
166 |
|
---|
167 | To use a specific C compiler for compiling Open vSwitch user
|
---|
168 | programs, also specify it on the configure command line, like so:
|
---|
169 |
|
---|
170 | % ./configure CC=gcc-4.2
|
---|
171 |
|
---|
172 | To build the Linux kernel module, so that you can run the
|
---|
173 | kernel-based switch, pass the location of the kernel build
|
---|
174 | directory on --with-l26. For example, to build for a running
|
---|
175 | instance of Linux 2.6:
|
---|
176 |
|
---|
177 | % ./configure --with-l26=/lib/modules/`uname -r`/build
|
---|
178 |
|
---|
179 | If you wish to build the kernel module for an architecture other
|
---|
180 | than the architecture of the machine used for the build, you may
|
---|
181 | specify the kernel architecture string using the KARCH variable
|
---|
182 | when invoking the configure script. For example, to build for MIPS
|
---|
183 | with Linux 2.6:
|
---|
184 |
|
---|
185 | % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips
|
---|
186 |
|
---|
187 | The configure script accepts a number of other options and honors
|
---|
188 | additional environment variables. For a full list, invoke
|
---|
189 | configure with the --help option.
|
---|
190 |
|
---|
191 | 3. Run make in the top source directory:
|
---|
192 |
|
---|
193 | % make
|
---|
194 |
|
---|
195 | 4. Become root by running "su" or another program.
|
---|
196 |
|
---|
197 | 5. Run "make install" to install the executables and manpages into the
|
---|
198 | running system, by default under /usr/local.
|
---|
199 |
|
---|
200 | 6. If you built kernel modules, you may load them with "insmod", e.g.:
|
---|
201 |
|
---|
202 | % insmod datapath/linux-2.6/openvswitch_mod.ko
|
---|
203 |
|
---|
204 | You may need to specify a full path to insmod, e.g. /sbin/insmod.
|
---|
205 | To verify that the modules have been loaded, run "/sbin/lsmod" and
|
---|
206 | check that openvswitch_mod is listed.
|
---|
207 |
|
---|
208 | If the "insmod" operation fails, look at the last few kernel log
|
---|
209 | messages (e.g. with "dmesg | tail"):
|
---|
210 |
|
---|
211 | - The message "openvswitch_mod: exports duplicate symbol
|
---|
212 | br_should_route_hook (owned by bridge)" means that the bridge
|
---|
213 | module is loaded. Run "/sbin/rmmod bridge" to remove it.
|
---|
214 |
|
---|
215 | If "/sbin/rmmod bridge" fails with "ERROR: Module bridge does
|
---|
216 | not exist in /proc/modules", then the bridge is compiled into
|
---|
217 | the kernel, rather than as a module. Open vSwitch does not
|
---|
218 | support this configuration (see "Build Requirements", above).
|
---|
219 |
|
---|
220 | - The message "openvswitch_mod: exports duplicate symbol
|
---|
221 | dp_ioctl_hook (owned by ofdatapath)" means that the ofdatapath
|
---|
222 | module from the OpenFlow reference implementation is loaded.
|
---|
223 | Run "/sbin/rmmod ofdatapath" to remove it. (You might have to
|
---|
224 | delete any existing datapaths beforehand, using the "dpctl"
|
---|
225 | program included with the OpenFlow reference implementation.
|
---|
226 | "ovs-dpctl" will not work.)
|
---|
227 |
|
---|
228 | - Otherwise, the most likely problem is that Open vSwitch was
|
---|
229 | built for a kernel different from the one into which you are
|
---|
230 | trying to load it. Run "modinfo" on openvswitch_mod.ko and on
|
---|
231 | a module built for the running kernel, e.g.:
|
---|
232 |
|
---|
233 | % /sbin/modinfo openvswitch_mod.ko
|
---|
234 | % /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko
|
---|
235 |
|
---|
236 | Compare the "vermagic" lines output by the two commands. If
|
---|
237 | they differ, then Open vSwitch was built for the wrong kernel.
|
---|
238 |
|
---|
239 | - If you decide to report a bug or ask a question related to
|
---|
240 | module loading, please include the output from the "dmesg" and
|
---|
241 | "modinfo" commands mentioned above.
|
---|
242 |
|
---|
243 | There is an optional module parameter to openvswitch_mod.ko called
|
---|
244 | vlan_tso that enables TCP segmentation offload over VLANs on NICs
|
---|
245 | that support it. Many drivers do not expose support for TSO on VLANs
|
---|
246 | in a way that Open vSwitch can use but there is no way to detect
|
---|
247 | whether this is the case. If you know that your particular driver can
|
---|
248 | handle it (for example by testing sending large TCP packets over VLANs)
|
---|
249 | then passing in a value of 1 may improve performance. Modules built for
|
---|
250 | Linux kernels 2.6.37 and later, as well as specially patched versions
|
---|
251 | of earlier kernels, do not need this and do not have this parameter. If
|
---|
252 | you do not understand what this means or do not know if your driver
|
---|
253 | will work, do not set this.
|
---|
254 |
|
---|
255 | 7. Initialize the configuration database using ovsdb-tool, e.g.:
|
---|
256 |
|
---|
257 | % mkdir -p /usr/local/etc/openvswitch
|
---|
258 | % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
|
---|
259 |
|
---|
260 | Startup
|
---|
261 | =======
|
---|
262 |
|
---|
263 | Before starting ovs-vswitchd itself, you need to start its
|
---|
264 | configuration database, ovsdb-server. Each machine on which Open
|
---|
265 | vSwitch is installed should run its own copy of ovsdb-server.
|
---|
266 | Configure it to use the database you created during step 7 of
|
---|
267 | installation, above, to listen on a Unix domain socket, to connect to
|
---|
268 | any managers specified in the database itself, and to use the SSL
|
---|
269 | configuration in the database:
|
---|
270 |
|
---|
271 | % ovsdb-server /usr/local/etc/openvswitch/conf.db \
|
---|
272 | --remote=punix:/usr/local/var/run/openvswitch/db.sock \
|
---|
273 | --remote=db:Open_vSwitch,manager_options \
|
---|
274 | --private-key=db:SSL,private_key \
|
---|
275 | --certificate=db:SSL,certificate \
|
---|
276 | --bootstrap-ca-cert=db:SSL,ca_cert \
|
---|
277 | --pidfile --detach
|
---|
278 |
|
---|
279 | (If you built Open vSwitch without SSL support, then omit
|
---|
280 | --private-key, --certificate, and --bootstrap-ca-cert.)
|
---|
281 |
|
---|
282 | Then initialize the database using ovs-vsctl. This is only
|
---|
283 | necessary the first time after you create the database with
|
---|
284 | ovsdb-tool (but running it at any time is harmless):
|
---|
285 |
|
---|
286 | % ovs-vsctl --no-wait init
|
---|
287 |
|
---|
288 | Then start the main Open vSwitch daemon, telling it to connect to the
|
---|
289 | same Unix domain socket:
|
---|
290 |
|
---|
291 | % ovs-vswitchd unix:/usr/local/var/run/openvswitch/db.sock \
|
---|
292 | --pidfile --detach
|
---|
293 |
|
---|
294 | Now you may use ovs-vsctl to set up bridges and other Open vSwitch
|
---|
295 | features. For example, to create a bridge named br0 and add ports
|
---|
296 | eth0 and vif1.0 to it:
|
---|
297 |
|
---|
298 | % ovs-vsctl add-br br0
|
---|
299 | % ovs-vsctl add-port br0 eth0
|
---|
300 | % ovs-vsctl add-port br0 vif1.0
|
---|
301 |
|
---|
302 | Please refer to ovs-vsctl(8) for more details.
|
---|
303 |
|
---|
304 | Upgrading
|
---|
305 | =========
|
---|
306 |
|
---|
307 | When you upgrade Open vSwitch from one version to another, you should
|
---|
308 | also upgrade the database schema:
|
---|
309 |
|
---|
310 | 1. Stop the Open vSwitch daemons, e.g.:
|
---|
311 |
|
---|
312 | % kill `cd /usr/local/var/run && cat ovsdb-server.pid ovs-vswitchd.pid`
|
---|
313 |
|
---|
314 | 2. Install the new Open vSwitch release.
|
---|
315 |
|
---|
316 | 3. Upgrade the database, in one of the following two ways:
|
---|
317 |
|
---|
318 | - If there is no important data in your database, then you may
|
---|
319 | delete the database file and recreate it with ovsdb-tool,
|
---|
320 | following the instructions under "Building and Installing Open
|
---|
321 | vSwitch for Linux".
|
---|
322 |
|
---|
323 | - If you want to preserve the contents of your database, back it
|
---|
324 | up first, then use "ovsdb-tool convert" to upgrade it, e.g.:
|
---|
325 |
|
---|
326 | % ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
|
---|
327 |
|
---|
328 | 4. Start the Open vSwitch daemons as described under "Building and
|
---|
329 | Installing Open vSwitch for Linux" above.
|
---|
330 |
|
---|
331 | Bug Reporting
|
---|
332 | -------------
|
---|
333 |
|
---|
334 | Please report problems to bugs@openvswitch.org.
|
---|