]>
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 | ||
51 | - To build a kernel module, you need the same version of GCC that | |
52 | was used to build that kernel. | |
53 | ||
54 | - A kernel build directory corresponding to the Linux kernel image | |
55 | the module is to run on. Under Debian and Ubuntu, for example, | |
56 | each linux-image package containing a kernel binary has a | |
57 | corresponding linux-headers package with the required build | |
58 | infrastructure. | |
59 | ||
60 | If you are working from a Git tree or snapshot (instead of from a | |
61 | distribution tarball), or if you modify the Open vSwitch build system, | |
62 | you will also need the following software: | |
63 | ||
37c98952 | 64 | - Autoconf version 2.63 or later. |
4b11d5e8 BP |
65 | |
66 | - Automake version 1.10 or later. | |
67 | ||
68 | - pkg-config. We test with version 0.22. | |
69 | ||
195b5c35 BP |
70 | - Python 2.x, for x >= 4. |
71 | ||
4b11d5e8 BP |
72 | Installation Requirements |
73 | ------------------------- | |
74 | ||
75 | The machine on which Open vSwitch is to be installed must have the | |
76 | following software: | |
77 | ||
78 | - libc compatible with the libc used for build. | |
79 | ||
80 | - libssl compatible with the libssl used for build, if OpenSSL was | |
81 | used for the build. | |
82 | ||
83 | - The Linux kernel version configured as part of the build. | |
84 | ||
85 | - For optional support of ingress policing, the "tc" program from | |
86 | iproute2 (part of all major distributions and available at | |
87 | http://www.linux-foundation.org/en/Net:Iproute2). | |
88 | ||
89 | - For debugging purposes, Open vSwitch expects that "tcpdump" is | |
90 | installed as /usr/sbin/tcpdump. If tcpdump is not installed, or | |
91 | if it is installed in a different location, then some Open | |
92 | vSwitch log messages will not be as detailed. | |
93 | ||
94 | Building and Installing Open vSwitch for Linux | |
95 | ============================================== | |
96 | ||
97 | Once you have installed all the prerequisites listed above in the Base | |
98 | Prerequisites section, follow the procedure below to build. | |
99 | ||
30746a1b JP |
100 | 1. If you pulled the sources directly from an Open vSwitch Git tree, |
101 | run boot.sh in the top source directory: | |
102 | ||
103 | % ./boot.sh | |
104 | ||
105 | 2. In the top source directory, configure the package by running the | |
4b11d5e8 BP |
106 | configure script. You can usually invoke configure without any |
107 | arguments: | |
108 | ||
109 | % ./configure | |
110 | ||
111 | By default all files are installed under /usr/local. If you want | |
112 | to install into, e.g., /usr and /var instead of /usr/local and | |
113 | /usr/local/var, add options as shown here: | |
114 | ||
115 | % ./configure --prefix=/usr --localstatedir=/var | |
116 | ||
117 | To use a specific C compiler for compiling Open vSwitch user | |
118 | programs, also specify it on the configure command line, like so: | |
119 | ||
120 | % ./configure CC=gcc-4.2 | |
121 | ||
122 | To build the Linux kernel module, so that you can run the | |
123 | kernel-based switch, pass the location of the kernel build | |
124 | directory on --with-l26. For example, to build for a running | |
125 | instance of Linux 2.6: | |
126 | ||
127 | % ./configure --with-l26=/lib/modules/`uname -r`/build | |
128 | ||
129 | If you wish to build the kernel module for an architecture other | |
130 | than the architecture of the machine used for the build, you may | |
131 | specify the kernel architecture string using the KARCH variable | |
132 | when invoking the configure script. For example, to build for MIPS | |
133 | with Linux 2.6: | |
134 | ||
135 | % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips | |
136 | ||
137 | The configure script accepts a number of other options and honors | |
138 | additional environment variables. For a full list, invoke | |
139 | configure with the --help option. | |
140 | ||
30746a1b | 141 | 3. Run make in the top source directory: |
4b11d5e8 BP |
142 | |
143 | % make | |
144 | ||
30746a1b | 145 | 4. Become root by running "su" or another program. |
4b11d5e8 | 146 | |
30746a1b | 147 | 5. Run "make install" to install the executables and manpages into the |
4b11d5e8 BP |
148 | running system, by default under /usr/local. |
149 | ||
30746a1b | 150 | 6. If you built kernel modules, you may load them with "insmod", e.g.: |
4b11d5e8 BP |
151 | |
152 | % insmod datapath/linux-2.6/openvswitch_mod.ko | |
153 | ||
154 | You may need to specify a full path to insmod, e.g. /sbin/insmod. | |
155 | To verify that the modules have been loaded, run "/sbin/lsmod" and | |
156 | check that openvswitch_mod is listed. | |
157 | ||
158 | Configuration | |
159 | ============= | |
160 | ||
161 | Open vSwitch is configured primarily through a configuration file, | |
162 | whose name is specified on the ovs-vswitchd command line. Please | |
163 | refer to ovs-vswitchd(8) and ovs-vswitchd.conf(5) for information on | |
164 | how to start ovs-vswitchd and the syntax of its configuration file, | |
165 | respectively. | |
166 | ||
167 | At runtime, you may make ovs-vswitchd reload its configuration file | |
168 | and update its configuration accordingly by sending it a SIGHUP | |
3fbe1d30 | 169 | signal. The ovs-appctl utility can also be used to do this: |
4b11d5e8 | 170 | |
3fbe1d30 | 171 | % ovs-appctl vswitchd/reload |
4b11d5e8 | 172 | |
3fbe1d30 BP |
173 | In the latter case, ovs-appctl will wait for ovs-vswitchd to finish |
174 | reloading before it exits. | |
4b11d5e8 BP |
175 | |
176 | Bug Reporting | |
177 | ------------- | |
178 | ||
37ea6436 | 179 | Please report problems to bugs@openvswitch.org. |