1 README.Debian for openvswitch-switch
2 ---------------------------------
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:
8 * Use a Linux kernel 3.3 or later, which has an integrated Open
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
17 * Install the "openvswitch-datapath-dkms" Debian package that
18 you built earlier. This should automatically build and
19 install the Open vSwitch kernel module for your running
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.
26 * Install the "openvswitch-datapath-source" Debian package, use
27 "module-assistant" to build a Debian package of the Open
28 vSwitch kernel module for your kernel, and then install that
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.
37 /usr/share/doc/openvswitch-datapath-source/README.Debian has
38 details on the build process.
40 * Build and install the kernel module by hand.
43 Debian network scripts (ifupdown) integration
44 ------------------------------------------------
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.
49 The stanzas that configure the OVS bridges should begin with "allow-ovs"
50 followed by name of the bridge. Here is an example.
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.
57 The following OVS specific "command" options are supported:
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
64 - ovs_ports: This option specifies all the ports that belong to a bridge.
66 - ovs_bridge: This options specifies a bridge to which a port belongs.
67 This is a required option for a port.
69 - ovs_bonds: This option specifies the list of physical interfaces to be
72 - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies
73 the patch's peer on the other bridge.
75 - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
76 For example, "gre", "vxlan", etc.
78 - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
79 used to specify the tunnel options like remote_ip, key, etc.
81 - ovs_options: This option lets you add extra arguments to a ovs-vsctl
82 command. See examples.
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
90 More implementation specific details can be seen in the examples.
94 ex 1: A standalone bridge.
102 ex 2: A bridge with one port.
110 iface eth0 inet manual
114 ex 3: A bridge with multiple physical ports.
122 iface eth0 inet manual
127 iface eth1 inet manual
131 ex 4: A bridge with an OVS internal port.
134 iface br1 inet static
136 netmask 255.255.255.0
141 iface vlan100 inet manual
145 ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)
150 iface br2 inet static
152 netmask 255.255.255.0
157 iface bond0 inet manual
161 ovs_options bond_mode=balance-tcp lacp=active
166 iface br0 inet manual
171 iface patch0 inet manual
173 ovs_type OVSPatchPort
174 ovs_patch_peer patch1
177 iface br1 inet manual
182 iface patch1 inet manual
184 ovs_type OVSPatchPort
185 ovs_patch_peer patch0
190 iface br1 inet static
192 netmask 255.255.255.0
197 iface gre1 inet manual
201 ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1
203 ex 8: Create and destroy bridges.
205 ifup --allow=ovs $list_of_bridges
206 ifdown --allow=ovs $list_of_bridges
208 Open vSwitch integration with systemd-networkd
209 -----------------------------------------------
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.
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.
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
239 Please note how the DHCP ClientIdentifier above has been configured with the
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:
250 Now create a new .network configuration file for "br-ens160". Something like:
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:
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
277 br-ens160 should now have the same DHCP IP. It should also have the correct
278 DNS resolution servers configured.
280 Notes on dependencies:
281 ---------------------
283 openvswitch-switch depends on $network, $named $remote_fs and $syslog to start.
284 This creates some startup dependency issues.
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.
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.
297 * Ideally, an admin should not add openvswitch bridges in the 'auto'
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
300 working on bridges listed in 'auto', openvswitch has not yet started.
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.
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