]>
Commit | Line | Data |
---|---|---|
064af421 BP |
1 | README.Debian for openvswitch-switch |
2 | --------------------------------- | |
3 | ||
f085ba1e BP |
4 | To use the Linux kernel-based switch implementation, you will need an |
5 | Open vSwitch kernel module. There are multiple ways to obtain one. | |
6 | In order of increasing manual effort, these are: | |
064af421 | 7 | |
f085ba1e | 8 | * Use a Linux kernel 3.3 or later, which has an integrated Open |
5a0e4aec | 9 | vSwitch kernel module. |
f085ba1e | 10 | |
5a0e4aec BP |
11 | The upstream Linux kernel module lacks a few features that |
12 | are in the third-party module. For details, please see the | |
13 | FAQ, "What features are not available in the Open vSwitch | |
14 | kernel datapath that ships as part of the upstream Linux | |
15 | kernel?". | |
f085ba1e BP |
16 | |
17 | * Install the "openvswitch-datapath-dkms" Debian package that | |
5a0e4aec BP |
18 | you built earlier. This should automatically build and |
19 | install the Open vSwitch kernel module for your running | |
20 | kernel. | |
f085ba1e | 21 | |
5a0e4aec BP |
22 | This option requires that you have a compiler and toolchain |
23 | installed on the machine where you run Open vSwitch, which | |
24 | may be unacceptable in some production server environments. | |
f085ba1e BP |
25 | |
26 | * Install the "openvswitch-datapath-source" Debian package, use | |
5a0e4aec BP |
27 | "module-assistant" to build a Debian package of the Open |
28 | vSwitch kernel module for your kernel, and then install that | |
29 | Debian package. | |
30 | ||
31 | You can install the kernel module Debian packages that you | |
32 | build this way on the same machine where you built it or on | |
33 | another machine or machines, which means that you don't | |
34 | necessarily have to have any build infrastructure on the | |
35 | machines where you use the kernel module. | |
36 | ||
37 | /usr/share/doc/openvswitch-datapath-source/README.Debian has | |
38 | details on the build process. | |
f085ba1e BP |
39 | |
40 | * Build and install the kernel module by hand. | |
064af421 | 41 | |
86b87c92 | 42 | |
1f00f85c GS |
43 | Debian network scripts (ifupdown) integration |
44 | ------------------------------------------------ | |
86b87c92 GS |
45 | This package lets a user to optionally configure Open vSwitch bridges |
46 | and ports from /etc/network/interfaces. Please refer to the interfaces(5) | |
47 | manpage for more details regarding /etc/network/interfaces. | |
48 | ||
49 | The stanzas that configure the OVS bridges should begin with "allow-ovs" | |
50 | followed by name of the bridge. Here is an example. | |
51 | allow-ovs br0 | |
52 | ||
53 | The stanzas that configure the OVS ports should begin with | |
54 | "allow-${bridge-name}" followed by name of the port. Here is an example. | |
55 | allow-br0 eth0 | |
56 | ||
57 | The following OVS specific "command" options are supported: | |
58 | ||
5b245e73 GS |
59 | - ovs_type: This can either be OVSBridge, OVSPort, OVSIntPort, OVSBond, |
60 | OVSPatchPort or OVSTunnel depending on whether you configure a bridge, | |
61 | port, an internal port, a bond, a patch port or a tunnel. This is a | |
62 | required option. | |
86b87c92 GS |
63 | |
64 | - ovs_ports: This option specifies all the ports that belong to a bridge. | |
65 | ||
66 | - ovs_bridge: This options specifies a bridge to which a port belongs. | |
67 | This is a required option for a port. | |
68 | ||
69 | - ovs_bonds: This option specifies the list of physical interfaces to be | |
70 | bonded together. | |
71 | ||
5b245e73 GS |
72 | - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies |
73 | the patch's peer on the other bridge. | |
74 | ||
364e0394 GS |
75 | - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel. |
76 | For example, "gre", "vxlan", etc. | |
77 | ||
78 | - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be | |
79 | used to specify the tunnel options like remote_ip, key, etc. | |
80 | ||
86b87c92 GS |
81 | - ovs_options: This option lets you add extra arguments to a ovs-vsctl |
82 | command. See examples. | |
83 | ||
84 | - ovs_extra: This option lets you run additional ovs-vsctl commands, | |
85 | separated by "--" (double dash). Variables can be part of the "ovs_extra" | |
86 | option. You can provide all the standard environmental variables | |
87 | described in the interfaces(5) man page. You can also pass shell | |
88 | commands. | |
89 | ||
90 | More implementation specific details can be seen in the examples. | |
91 | ||
92 | Examples: | |
93 | -------- | |
94 | ex 1: A standalone bridge. | |
95 | ||
96 | allow-ovs br0 | |
97 | iface br0 inet static | |
98 | address 192.168.1.1 | |
99 | netmask 255.255.255.0 | |
100 | ovs_type OVSBridge | |
101 | ||
102 | ex 2: A bridge with one port. | |
103 | ||
104 | allow-ovs br0 | |
105 | iface br0 inet dhcp | |
106 | ovs_type OVSBridge | |
107 | ovs_ports eth0 | |
108 | ||
109 | allow-br0 eth0 | |
110 | iface eth0 inet manual | |
111 | ovs_bridge br0 | |
112 | ovs_type OVSPort | |
113 | ||
114 | ex 3: A bridge with multiple physical ports. | |
115 | ||
116 | allow-ovs br0 | |
117 | iface br0 inet dhcp | |
118 | ovs_type OVSBridge | |
119 | ovs_ports eth0 eth1 | |
120 | ||
121 | allow-br0 eth0 | |
122 | iface eth0 inet manual | |
123 | ovs_bridge br0 | |
124 | ovs_type OVSPort | |
125 | ||
126 | allow-br0 eth1 | |
127 | iface eth1 inet manual | |
128 | ovs_bridge br0 | |
129 | ovs_type OVSPort | |
130 | ||
131 | ex 4: A bridge with an OVS internal port. | |
132 | ||
133 | allow-ovs br1 | |
134 | iface br1 inet static | |
135 | address 192.168.1.1 | |
136 | netmask 255.255.255.0 | |
137 | ovs_type OVSBridge | |
138 | ovs_ports vlan100 | |
139 | ||
140 | allow-br1 vlan100 | |
141 | iface vlan100 inet manual | |
142 | ovs_bridge br1 | |
143 | ovs_type OVSIntPort | |
144 | ovs_options tag=100 | |
145 | ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s) | |
146 | ||
147 | ex 5: Bonding. | |
148 | ||
149 | allow-ovs br2 | |
150 | iface br2 inet static | |
151 | address 192.170.1.1 | |
152 | netmask 255.255.255.0 | |
153 | ovs_type OVSBridge | |
154 | ovs_ports bond0 | |
155 | ||
156 | allow-br2 bond0 | |
157 | iface bond0 inet manual | |
158 | ovs_bridge br2 | |
159 | ovs_type OVSBond | |
160 | ovs_bonds eth2 eth3 | |
161 | ovs_options bond_mode=balance-tcp lacp=active | |
162 | ||
5b245e73 GS |
163 | ex 6: Patch ports. |
164 | ||
165 | allow-ovs br0 | |
166 | iface br0 inet manual | |
167 | ovs_type OVSBridge | |
168 | ovs_ports patch0 | |
169 | ||
170 | allow-br0 patch0 | |
171 | iface patch0 inet manual | |
172 | ovs_bridge br0 | |
173 | ovs_type OVSPatchPort | |
174 | ovs_patch_peer patch1 | |
175 | ||
176 | allow-ovs br1 | |
177 | iface br1 inet manual | |
178 | ovs_type OVSBridge | |
179 | ovs_ports patch1 | |
180 | ||
181 | allow-br1 patch1 | |
182 | iface patch1 inet manual | |
183 | ovs_bridge br1 | |
184 | ovs_type OVSPatchPort | |
185 | ovs_patch_peer patch0 | |
186 | ||
187 | ex 7: Tunnel. | |
364e0394 GS |
188 | |
189 | allow-ovs br1 | |
190 | iface br1 inet static | |
191 | address 192.168.1.1 | |
192 | netmask 255.255.255.0 | |
193 | ovs_type OVSBridge | |
194 | ovs_ports gre1 | |
195 | ||
196 | allow-br1 gre1 | |
197 | iface gre1 inet manual | |
198 | ovs_bridge br1 | |
199 | ovs_type OVSTunnel | |
200 | ovs_tunnel_type gre | |
201 | ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1 | |
202 | ||
5b245e73 | 203 | ex 8: Create and destroy bridges. |
86b87c92 GS |
204 | |
205 | ifup --allow=ovs $list_of_bridges | |
206 | ifdown --allow=ovs $list_of_bridges | |
9a8b5cc1 | 207 | |
1f00f85c GS |
208 | Open vSwitch integration with systemd-networkd |
209 | ----------------------------------------------- | |
210 | ||
211 | There is no native integration of OVS with systemd-networkd. That is, | |
212 | you cannot create OVS bridges, ports and bonds by simply writing configuration | |
213 | files in /etc/systemd/network. But, you can create OVS devices using ovs-vsctl | |
214 | and then write configuration files to provide them IP addresses. | |
215 | ||
216 | As soon as a OVS device is visible, systemd-networkd will provide that device | |
217 | an IP address. Since OVS database is persistent across reboots, the OVS | |
218 | devices will get re-created after a reboot as soon as OVS startup script is | |
219 | invoked. And systemd-networkd will immediately assign the configuration defined | |
220 | in /etc/systemd/network. | |
221 | ||
222 | Example: | |
223 | ||
224 | If you have a physical ethernet device "ens160" which has been configured with | |
225 | DHCP, your systemd-networkd's .network config file will look something like | |
226 | this: | |
227 | ||
228 | ``` | |
229 | [Match] | |
230 | Name=ens160 | |
231 | ||
232 | [Network] | |
233 | DHCP=ipv4 | |
234 | ||
235 | [DHCP] | |
236 | ClientIdentifier=mac | |
237 | ``` | |
238 | ||
239 | Please note how the DHCP ClientIdentifier above has been configured with the | |
240 | mac address. | |
241 | ||
242 | To create a OVS bridge "br-ens160" and add "ens160" as a port of that | |
243 | bridge, you can change the .network configuration for "ens160" to look like: | |
244 | ||
245 | ``` | |
246 | [Match] | |
247 | Name=ens160 | |
248 | ``` | |
249 | ||
250 | Now create a new .network configuration file for "br-ens160". Something like: | |
251 | ||
252 | ``` | |
253 | [Match] | |
254 | Name=br-ens160 | |
255 | ||
256 | [Network] | |
257 | DHCP=ipv4 | |
258 | ||
259 | [DHCP] | |
260 | ClientIdentifier=mac | |
261 | ``` | |
262 | ||
263 | Now, use ovs-vsctl to create br-ens160 and add ens160 as a port of it. You | |
264 | will also have to flush the IP address of ens160 and restart systemd-networkd | |
265 | in the same line. It is important to let br-ens160 have the same mac address as | |
266 | ens160 to get the same IP address to br-ens160 from the DHCP server. In the | |
267 | below command, "$mac_of_ens160" holds the mac address of ens160. For e.g: | |
268 | ||
269 | ``` | |
270 | mac_of_ens160='"00:0c:29:77:27:7a"' | |
271 | ovs-vsctl --may-exist add-br br-ens160 -- \ | |
272 | --may-exist add-port br-ens160 ens160 -- \ | |
273 | set interface br-ens160 mac="$mac_of_ens160"; ip addr flush dev ens160; \ | |
274 | systemctl restart systemd-networkd | |
275 | ``` | |
276 | ||
277 | br-ens160 should now have the same DHCP IP. It should also have the correct | |
278 | DNS resolution servers configured. | |
279 | ||
9a8b5cc1 GS |
280 | Notes on dependencies: |
281 | --------------------- | |
282 | ||
283 | openvswitch-switch depends on $network, $named $remote_fs and $syslog to start. | |
284 | This creates some startup dependency issues. | |
285 | ||
286 | * Since openvswitch utilities are placed in /usr and /usr can be mounted | |
287 | through NFS, openvswitch has to start after it. But if a user uses openvswitch | |
288 | for all his networking needs and hence to mount NFS, there will be a deadlock. | |
289 | So, if /usr is mounted through NFS and openvswitch is used for all networking, | |
290 | the administrator should figure out a way to mount NFS before starting OVS. | |
291 | One way to do this is in initramfs. | |
292 | ||
293 | * Since openvswitch starts after $network, $remote_fs and $syslog, any startup | |
294 | script that depends on openvswitch but starts before it, needs to be changed | |
295 | to depend on openvswitch-switch too. | |
296 | ||
297 | * Ideally, an admin should not add openvswitch bridges in the 'auto' | |
e0dfd67b GS |
298 | section of the 'interfaces' file (i.e., if "br0" is a OVS bridge, you should |
299 | not have a line "auto br0"). This is because, when ifupdown starts | |
9a8b5cc1 GS |
300 | working on bridges listed in 'auto', openvswitch has not yet started. |
301 | ||
302 | But, if the admin wants to go down this route and adds openvswitch bridges | |
303 | in the 'auto' section, openvswitch-switch will forcefully be started when | |
304 | ifupdown kicks in. In a case like this, the admin needs to make sure that /usr | |
305 | has already been mounted and that a remote $syslog (if used) is ready to | |
306 | receive openvswitch logs. | |
e0dfd67b GS |
307 | |
308 | * With systemd, adding openvswitch bridges in the 'auto' section of the | |
309 | 'interfaces' file can cause race conditions (i.e., if "br0" is a OVS bridge, | |
310 | you should not have a line "auto br0"). Debian systems have added a | |
311 | systemd ifup@.service file. This file will call ifdown and ifup on interfaces | |
312 | in "auto" section automatically when the interfaces disappear and appear | |
313 | respectively. This will cause race conditions if you delete and add the same | |
314 | bridges using tools like "ovs-vsctl" or "ovs-dpctl". This is also a problem | |
315 | when you upgrade your openvswitch kernel module using commands like | |
316 | 'force-reload-kmod'. |