]>
Commit | Line | Data |
---|---|---|
4b11d5e8 BP |
1 | How to Install Open vSwitch on Linux |
2 | ==================================== | |
3 | ||
4 | This document describes how to build and install Open vSwitch on a | |
e5660bae | 5 | generic Linux host. If you want to install Open vSwitch on a Citrix |
404c1692 | 6 | XenServer, see INSTALL.XenServer instead. |
4b11d5e8 | 7 | |
90a249dc BP |
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". | |
4b11d5e8 BP |
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 | ||
9f8bf569 BP |
23 | - pkg-config. We test with version 0.22. |
24 | ||
4b11d5e8 BP |
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 | |
f272ec73 BP |
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. | |
4b11d5e8 | 31 | |
d377243b BP |
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. | |
4b11d5e8 BP |
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 | |
f8500004 JP |
49 | configuration options NET_CLS_BASIC, NET_SCH_INGRESS, and |
50 | NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is | |
51 | obsolete and not needed.) | |
4b11d5e8 | 52 | |
6f470982 JG |
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 | ||
c9d3af4e BP |
57 | To configure HTB or HFSC quality of service with Open vSwitch, |
58 | you must enable the respective configuration options. | |
59 | ||
26bb189d BP |
60 | To use Open vSwitch support for TAP devices, you must enable |
61 | CONFIG_TUN. | |
62 | ||
4b11d5e8 BP |
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 | |
c9d3af4e BP |
73 | distribution tarball), or if you modify the Open vSwitch build system |
74 | or the database schema, you will also need the following software: | |
4b11d5e8 | 75 | |
55aa00e0 | 76 | - Autoconf version 2.64 or later. |
4b11d5e8 BP |
77 | |
78 | - Automake version 1.10 or later. | |
79 | ||
195b5c35 BP |
80 | - Python 2.x, for x >= 4. |
81 | ||
436f27dd AS |
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 | ||
c9d3af4e BP |
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 | ||
f8d739a9 BP |
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 | ||
c9d3af4e BP |
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 | ||
f8f26e98 BP |
103 | If you are going to extensively modify Open vSwitch, please consider |
104 | installing the following to obtain better warnings: | |
105 | ||
106 | - "sparse" version 0.4.4 or later | |
107 | (http://www.kernel.org/pub/software/devel/sparse/dist/). | |
108 | ||
109 | - GNU make. | |
110 | ||
4b11d5e8 BP |
111 | Installation Requirements |
112 | ------------------------- | |
113 | ||
114 | The machine on which Open vSwitch is to be installed must have the | |
115 | following software: | |
116 | ||
117 | - libc compatible with the libc used for build. | |
118 | ||
119 | - libssl compatible with the libssl used for build, if OpenSSL was | |
120 | used for the build. | |
121 | ||
122 | - The Linux kernel version configured as part of the build. | |
123 | ||
124 | - For optional support of ingress policing, the "tc" program from | |
125 | iproute2 (part of all major distributions and available at | |
126 | http://www.linux-foundation.org/en/Net:Iproute2). | |
127 | ||
26bb189d BP |
128 | You should ensure that /dev/urandom exists. To support TAP devices, |
129 | you must also ensure that /dev/net/tun exists. | |
6e8e271c | 130 | |
2ac7bbf5 | 131 | To run the ovsdbmonitor tool, the machine must also have the following |
436f27dd AS |
132 | software: |
133 | ||
134 | - Python 2.x, for x >= 4. | |
135 | ||
136 | - Python Twisted Conch. | |
137 | ||
138 | - Python JSON. | |
139 | ||
140 | - PySide or PyQt4. | |
141 | ||
142 | - Python Zope interface module. | |
143 | ||
144 | (On Debian "lenny" the above can be installed with "apt-get install | |
145 | python-json python-qt4 python-zopeinterface python-twisted-conch".) | |
146 | ||
4b11d5e8 BP |
147 | Building and Installing Open vSwitch for Linux |
148 | ============================================== | |
149 | ||
150 | Once you have installed all the prerequisites listed above in the Base | |
151 | Prerequisites section, follow the procedure below to build. | |
152 | ||
30746a1b JP |
153 | 1. If you pulled the sources directly from an Open vSwitch Git tree, |
154 | run boot.sh in the top source directory: | |
155 | ||
156 | % ./boot.sh | |
157 | ||
158 | 2. In the top source directory, configure the package by running the | |
4b11d5e8 BP |
159 | configure script. You can usually invoke configure without any |
160 | arguments: | |
161 | ||
162 | % ./configure | |
163 | ||
164 | By default all files are installed under /usr/local. If you want | |
165 | to install into, e.g., /usr and /var instead of /usr/local and | |
166 | /usr/local/var, add options as shown here: | |
167 | ||
168 | % ./configure --prefix=/usr --localstatedir=/var | |
169 | ||
170 | To use a specific C compiler for compiling Open vSwitch user | |
171 | programs, also specify it on the configure command line, like so: | |
172 | ||
173 | % ./configure CC=gcc-4.2 | |
174 | ||
175 | To build the Linux kernel module, so that you can run the | |
176 | kernel-based switch, pass the location of the kernel build | |
338fb44a | 177 | directory on --with-linux. For example, to build for a running |
8a2d6596 | 178 | instance of Linux: |
4b11d5e8 | 179 | |
8a2d6596 | 180 | % ./configure --with-linux=/lib/modules/`uname -r`/build |
4b11d5e8 BP |
181 | |
182 | If you wish to build the kernel module for an architecture other | |
183 | than the architecture of the machine used for the build, you may | |
184 | specify the kernel architecture string using the KARCH variable | |
185 | when invoking the configure script. For example, to build for MIPS | |
8a2d6596 | 186 | with Linux: |
4b11d5e8 | 187 | |
22bcc0e7 | 188 | % ./configure --with-linux=/path/to/linux KARCH=mips |
4b11d5e8 BP |
189 | |
190 | The configure script accepts a number of other options and honors | |
191 | additional environment variables. For a full list, invoke | |
192 | configure with the --help option. | |
193 | ||
30746a1b | 194 | 3. Run make in the top source directory: |
4b11d5e8 BP |
195 | |
196 | % make | |
197 | ||
f8f26e98 BP |
198 | For improved warnings if you installed "sparse" (see |
199 | "Prerequisites"), add C=1 to the "make" command line. | |
200 | ||
30746a1b | 201 | 4. Become root by running "su" or another program. |
4b11d5e8 | 202 | |
30746a1b | 203 | 5. Run "make install" to install the executables and manpages into the |
4b11d5e8 BP |
204 | running system, by default under /usr/local. |
205 | ||
30746a1b | 206 | 6. If you built kernel modules, you may load them with "insmod", e.g.: |
4b11d5e8 | 207 | |
9b80f761 | 208 | % insmod datapath/linux/openvswitch.ko |
4b11d5e8 BP |
209 | |
210 | You may need to specify a full path to insmod, e.g. /sbin/insmod. | |
211 | To verify that the modules have been loaded, run "/sbin/lsmod" and | |
9b80f761 | 212 | check that openvswitch is listed. |
4b11d5e8 | 213 | |
dd2d79ce BP |
214 | If the "insmod" operation fails, look at the last few kernel log |
215 | messages (e.g. with "dmesg | tail"): | |
216 | ||
9b80f761 | 217 | - The message "openvswitch: exports duplicate symbol |
dd2d79ce BP |
218 | br_should_route_hook (owned by bridge)" means that the bridge |
219 | module is loaded. Run "/sbin/rmmod bridge" to remove it. | |
220 | ||
221 | If "/sbin/rmmod bridge" fails with "ERROR: Module bridge does | |
222 | not exist in /proc/modules", then the bridge is compiled into | |
223 | the kernel, rather than as a module. Open vSwitch does not | |
224 | support this configuration (see "Build Requirements", above). | |
225 | ||
9b80f761 | 226 | - The message "openvswitch: exports duplicate symbol |
dd2d79ce BP |
227 | dp_ioctl_hook (owned by ofdatapath)" means that the ofdatapath |
228 | module from the OpenFlow reference implementation is loaded. | |
229 | Run "/sbin/rmmod ofdatapath" to remove it. (You might have to | |
230 | delete any existing datapaths beforehand, using the "dpctl" | |
231 | program included with the OpenFlow reference implementation. | |
232 | "ovs-dpctl" will not work.) | |
233 | ||
234 | - Otherwise, the most likely problem is that Open vSwitch was | |
235 | built for a kernel different from the one into which you are | |
9b80f761 | 236 | trying to load it. Run "modinfo" on openvswitch.ko and on |
dd2d79ce BP |
237 | a module built for the running kernel, e.g.: |
238 | ||
9b80f761 | 239 | % /sbin/modinfo openvswitch.ko |
dd2d79ce BP |
240 | % /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko |
241 | ||
242 | Compare the "vermagic" lines output by the two commands. If | |
243 | they differ, then Open vSwitch was built for the wrong kernel. | |
244 | ||
245 | - If you decide to report a bug or ask a question related to | |
246 | module loading, please include the output from the "dmesg" and | |
247 | "modinfo" commands mentioned above. | |
248 | ||
9b80f761 | 249 | There is an optional module parameter to openvswitch.ko called |
3f6256af JG |
250 | vlan_tso that enables TCP segmentation offload over VLANs on NICs |
251 | that support it. Many drivers do not expose support for TSO on VLANs | |
252 | in a way that Open vSwitch can use but there is no way to detect | |
253 | whether this is the case. If you know that your particular driver can | |
254 | handle it (for example by testing sending large TCP packets over VLANs) | |
255 | then passing in a value of 1 may improve performance. Modules built for | |
431488e6 BP |
256 | Linux kernels 2.6.37 and later, as well as specially patched versions |
257 | of earlier kernels, do not need this and do not have this parameter. If | |
258 | you do not understand what this means or do not know if your driver | |
259 | will work, do not set this. | |
3f6256af | 260 | |
3b12adda | 261 | 7. Initialize the configuration database using ovsdb-tool, e.g.: |
4b11d5e8 | 262 | |
028415b6 BP |
263 | % mkdir -p /usr/local/etc/openvswitch |
264 | % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema | |
4b11d5e8 | 265 | |
3b12adda BP |
266 | Startup |
267 | ======= | |
4b11d5e8 | 268 | |
3b12adda | 269 | Before starting ovs-vswitchd itself, you need to start its |
cb8141b2 BP |
270 | configuration database, ovsdb-server. Each machine on which Open |
271 | vSwitch is installed should run its own copy of ovsdb-server. | |
272 | Configure it to use the database you created during step 7 of | |
8084a280 BP |
273 | installation, above, to listen on a Unix domain socket, to connect to |
274 | any managers specified in the database itself, and to use the SSL | |
275 | configuration in the database: | |
276 | ||
29701194 BP |
277 | % ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \ |
278 | --remote=db:Open_vSwitch,manager_options \ | |
279 | --private-key=db:SSL,private_key \ | |
280 | --certificate=db:SSL,certificate \ | |
281 | --bootstrap-ca-cert=db:SSL,ca_cert \ | |
282 | --pidfile --detach | |
3b12adda | 283 | |
d3e3fb58 BP |
284 | (If you built Open vSwitch without SSL support, then omit |
285 | --private-key, --certificate, and --bootstrap-ca-cert.) | |
286 | ||
de4f3c10 | 287 | Then initialize the database using ovs-vsctl. This is only |
332b4e09 BP |
288 | necessary the first time after you create the database with |
289 | ovsdb-tool (but running it at any time is harmless): | |
290 | ||
de4f3c10 | 291 | % ovs-vsctl --no-wait init |
332b4e09 | 292 | |
3b12adda BP |
293 | Then start the main Open vSwitch daemon, telling it to connect to the |
294 | same Unix domain socket: | |
295 | ||
80df177a | 296 | % ovs-vswitchd --pidfile --detach |
3b12adda BP |
297 | |
298 | Now you may use ovs-vsctl to set up bridges and other Open vSwitch | |
299 | features. For example, to create a bridge named br0 and add ports | |
300 | eth0 and vif1.0 to it: | |
301 | ||
302 | % ovs-vsctl add-br br0 | |
303 | % ovs-vsctl add-port br0 eth0 | |
304 | % ovs-vsctl add-port br0 vif1.0 | |
305 | ||
306 | Please refer to ovs-vsctl(8) for more details. | |
4b11d5e8 | 307 | |
8b055d92 BP |
308 | Upgrading |
309 | ========= | |
310 | ||
311 | When you upgrade Open vSwitch from one version to another, you should | |
312 | also upgrade the database schema: | |
313 | ||
314 | 1. Stop the Open vSwitch daemons, e.g.: | |
315 | ||
012f5c4b | 316 | % kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid` |
8b055d92 BP |
317 | |
318 | 2. Install the new Open vSwitch release. | |
319 | ||
320 | 3. Upgrade the database, in one of the following two ways: | |
321 | ||
322 | - If there is no important data in your database, then you may | |
323 | delete the database file and recreate it with ovsdb-tool, | |
324 | following the instructions under "Building and Installing Open | |
325 | vSwitch for Linux". | |
326 | ||
327 | - If you want to preserve the contents of your database, back it | |
328 | up first, then use "ovsdb-tool convert" to upgrade it, e.g.: | |
329 | ||
028415b6 | 330 | % ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema |
8b055d92 BP |
331 | |
332 | 4. Start the Open vSwitch daemons as described under "Building and | |
333 | Installing Open vSwitch for Linux" above. | |
334 | ||
4b11d5e8 BP |
335 | Bug Reporting |
336 | ------------- | |
337 | ||
37ea6436 | 338 | Please report problems to bugs@openvswitch.org. |