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 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 or
60 OVSTunnel depending on whether you configure a bridge, port, an internal
61 port, a bond or a tunnel. This is a required option.
63 - ovs_ports: This option specifies all the ports that belong to a bridge.
65 - ovs_bridge: This options specifies a bridge to which a port belongs.
66 This is a required option for a port.
68 - ovs_bonds: This option specifies the list of physical interfaces to be
71 - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
72 For example, "gre", "vxlan", etc.
74 - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
75 used to specify the tunnel options like remote_ip, key, etc.
77 - ovs_options: This option lets you add extra arguments to a ovs-vsctl
78 command. See examples.
80 - ovs_extra: This option lets you run additional ovs-vsctl commands,
81 separated by "--" (double dash). Variables can be part of the "ovs_extra"
82 option. You can provide all the standard environmental variables
83 described in the interfaces(5) man page. You can also pass shell
86 More implementation specific details can be seen in the examples.
90 ex 1: A standalone bridge.
98 ex 2: A bridge with one port.
106 iface eth0 inet manual
110 ex 3: A bridge with multiple physical ports.
118 iface eth0 inet manual
123 iface eth1 inet manual
127 ex 4: A bridge with an OVS internal port.
130 iface br1 inet static
132 netmask 255.255.255.0
137 iface vlan100 inet manual
141 ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)
146 iface br2 inet static
148 netmask 255.255.255.0
153 iface bond0 inet manual
157 ovs_options bond_mode=balance-tcp lacp=active
162 iface br1 inet static
164 netmask 255.255.255.0
169 iface gre1 inet manual
173 ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1
175 ex 7: Create and destroy bridges.
177 ifup --allow=ovs $list_of_bridges
178 ifdown --allow=ovs $list_of_bridges
180 Notes on dependencies:
181 ---------------------
183 openvswitch-switch depends on $network, $named $remote_fs and $syslog to start.
184 This creates some startup dependency issues.
186 * Since openvswitch utilities are placed in /usr and /usr can be mounted
187 through NFS, openvswitch has to start after it. But if a user uses openvswitch
188 for all his networking needs and hence to mount NFS, there will be a deadlock.
189 So, if /usr is mounted through NFS and openvswitch is used for all networking,
190 the administrator should figure out a way to mount NFS before starting OVS.
191 One way to do this is in initramfs.
193 * Since openvswitch starts after $network, $remote_fs and $syslog, any startup
194 script that depends on openvswitch but starts before it, needs to be changed
195 to depend on openvswitch-switch too.
197 * Ideally, an admin should not add openvswitch bridges in the 'auto'
198 section of the 'interfaces' file. This is because, when ifupdown starts
199 working on bridges listed in 'auto', openvswitch has not yet started.
201 But, if the admin wants to go down this route and adds openvswitch bridges
202 in the 'auto' section, openvswitch-switch will forcefully be started when
203 ifupdown kicks in. In a case like this, the admin needs to make sure that /usr
204 has already been mounted and that a remote $syslog (if used) is ready to
205 receive openvswitch logs.