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