README.Debian for openvswitch-switch
---------------------------------
-* The switch must be configured before it can be used. To configure
- it interactively, install the openvswitch-switch-config package and run
- the ovs-switch-setup program. Alternatively, edit
- /etc/default/openvswitch-switch by hand, then start the switch manually
- with "/etc/init.d/openvswitch-switch start".
+To use the Linux kernel-based switch implementation, you will need an
+Open vSwitch kernel module. There are multiple ways to obtain one.
+In order of increasing manual effort, these are:
-* To use the Linux kernel-based switch implementation, you will need
- to build and install the Open vSwitch kernel module. To do so, install
- the openvswitch-datapath-source package, then follow the instructions
- given in /usr/share/doc/openvswitch-datapath-source/README.Debian
+ * Use a Linux kernel 3.3 or later, which has an integrated Open
+ vSwitch kernel module.
-* This package does not yet support the userspace datapath-based
- switch implementation.
+ The upstream Linux kernel module lacks a few features that
+ are in the third-party module. For details, please see the
+ FAQ, "What features are not available in the Open vSwitch
+ kernel datapath that ships as part of the upstream Linux
+ kernel?".
- -- Ben Pfaff <blp@nicira.com>, Mon, 11 May 2009 13:29:43 -0700
+ * Install the "openvswitch-datapath-dkms" Debian package that
+ you built earlier. This should automatically build and
+ install the Open vSwitch kernel module for your running
+ kernel.
+
+ This option requires that you have a compiler and toolchain
+ installed on the machine where you run Open vSwitch, which
+ may be unacceptable in some production server environments.
+
+ * Install the "openvswitch-datapath-source" Debian package, use
+ "module-assistant" to build a Debian package of the Open
+ vSwitch kernel module for your kernel, and then install that
+ Debian package.
+
+ You can install the kernel module Debian packages that you
+ build this way on the same machine where you built it or on
+ another machine or machines, which means that you don't
+ necessarily have to have any build infrastructure on the
+ machines where you use the kernel module.
+
+ /usr/share/doc/openvswitch-datapath-source/README.Debian has
+ details on the build process.
+
+ * Build and install the kernel module by hand.
+
+
+Debian network scripts (ifupdown) integration
+------------------------------------------------
+This package lets a user to optionally configure Open vSwitch bridges
+and ports from /etc/network/interfaces. Please refer to the interfaces(5)
+manpage for more details regarding /etc/network/interfaces.
+
+The stanzas that configure the OVS bridges should begin with "allow-ovs"
+followed by name of the bridge. Here is an example.
+allow-ovs br0
+
+The stanzas that configure the OVS ports should begin with
+"allow-${bridge-name}" followed by name of the port. Here is an example.
+allow-br0 eth0
+
+The following OVS specific "command" options are supported:
+
+ - ovs_type: This can either be OVSBridge, OVSPort, OVSIntPort, OVSBond,
+ OVSPatchPort or OVSTunnel depending on whether you configure a bridge,
+ port, an internal port, a bond, a patch port or a tunnel. This is a
+ required option.
+
+ - ovs_ports: This option specifies all the ports that belong to a bridge.
+
+ - ovs_bridge: This options specifies a bridge to which a port belongs.
+ This is a required option for a port.
+
+ - ovs_bonds: This option specifies the list of physical interfaces to be
+ bonded together.
+
+ - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies
+ the patch's peer on the other bridge.
+
+ - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel.
+ For example, "gre", "vxlan", etc.
+
+ - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be
+ used to specify the tunnel options like remote_ip, key, etc.
+
+ - ovs_options: This option lets you add extra arguments to a ovs-vsctl
+ command. See examples.
+
+ - ovs_extra: This option lets you run additional ovs-vsctl commands,
+ separated by "--" (double dash). Variables can be part of the "ovs_extra"
+ option. You can provide all the standard environmental variables
+ described in the interfaces(5) man page. You can also pass shell
+ commands.
+
+More implementation specific details can be seen in the examples.
+
+Examples:
+--------
+ex 1: A standalone bridge.
+
+allow-ovs br0
+iface br0 inet static
+ address 192.168.1.1
+ netmask 255.255.255.0
+ ovs_type OVSBridge
+
+ex 2: A bridge with one port.
+
+allow-ovs br0
+iface br0 inet dhcp
+ ovs_type OVSBridge
+ ovs_ports eth0
+
+allow-br0 eth0
+iface eth0 inet manual
+ ovs_bridge br0
+ ovs_type OVSPort
+
+ex 3: A bridge with multiple physical ports.
+
+allow-ovs br0
+iface br0 inet dhcp
+ ovs_type OVSBridge
+ ovs_ports eth0 eth1
+
+allow-br0 eth0
+iface eth0 inet manual
+ ovs_bridge br0
+ ovs_type OVSPort
+
+allow-br0 eth1
+iface eth1 inet manual
+ ovs_bridge br0
+ ovs_type OVSPort
+
+ex 4: A bridge with an OVS internal port.
+
+allow-ovs br1
+iface br1 inet static
+ address 192.168.1.1
+ netmask 255.255.255.0
+ ovs_type OVSBridge
+ ovs_ports vlan100
+
+allow-br1 vlan100
+iface vlan100 inet manual
+ ovs_bridge br1
+ ovs_type OVSIntPort
+ ovs_options tag=100
+ ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s)
+
+ex 5: Bonding.
+
+allow-ovs br2
+iface br2 inet static
+ address 192.170.1.1
+ netmask 255.255.255.0
+ ovs_type OVSBridge
+ ovs_ports bond0
+
+allow-br2 bond0
+iface bond0 inet manual
+ ovs_bridge br2
+ ovs_type OVSBond
+ ovs_bonds eth2 eth3
+ ovs_options bond_mode=balance-tcp lacp=active
+
+ex 6: Patch ports.
+
+allow-ovs br0
+iface br0 inet manual
+ ovs_type OVSBridge
+ ovs_ports patch0
+
+allow-br0 patch0
+iface patch0 inet manual
+ ovs_bridge br0
+ ovs_type OVSPatchPort
+ ovs_patch_peer patch1
+
+allow-ovs br1
+iface br1 inet manual
+ ovs_type OVSBridge
+ ovs_ports patch1
+
+allow-br1 patch1
+iface patch1 inet manual
+ ovs_bridge br1
+ ovs_type OVSPatchPort
+ ovs_patch_peer patch0
+
+ex 7: Tunnel.
+
+allow-ovs br1
+iface br1 inet static
+ address 192.168.1.1
+ netmask 255.255.255.0
+ ovs_type OVSBridge
+ ovs_ports gre1
+
+allow-br1 gre1
+iface gre1 inet manual
+ ovs_bridge br1
+ ovs_type OVSTunnel
+ ovs_tunnel_type gre
+ ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1
+
+ex 8: Create and destroy bridges.
+
+ifup --allow=ovs $list_of_bridges
+ifdown --allow=ovs $list_of_bridges
+
+Open vSwitch integration with systemd-networkd
+-----------------------------------------------
+
+There is no native integration of OVS with systemd-networkd. That is,
+you cannot create OVS bridges, ports and bonds by simply writing configuration
+files in /etc/systemd/network. But, you can create OVS devices using ovs-vsctl
+and then write configuration files to provide them IP addresses.
+
+As soon as a OVS device is visible, systemd-networkd will provide that device
+an IP address. Since OVS database is persistent across reboots, the OVS
+devices will get re-created after a reboot as soon as OVS startup script is
+invoked. And systemd-networkd will immediately assign the configuration defined
+in /etc/systemd/network.
+
+Example:
+
+If you have a physical ethernet device "ens160" which has been configured with
+DHCP, your systemd-networkd's .network config file will look something like
+this:
+
+```
+[Match]
+Name=ens160
+
+[Network]
+DHCP=ipv4
+
+[DHCP]
+ClientIdentifier=mac
+```
+
+Please note how the DHCP ClientIdentifier above has been configured with the
+mac address.
+
+To create a OVS bridge "br-ens160" and add "ens160" as a port of that
+bridge, you can change the .network configuration for "ens160" to look like:
+
+```
+[Match]
+Name=ens160
+```
+
+Now create a new .network configuration file for "br-ens160". Something like:
+
+```
+[Match]
+Name=br-ens160
+
+[Network]
+DHCP=ipv4
+
+[DHCP]
+ClientIdentifier=mac
+```
+
+Now, use ovs-vsctl to create br-ens160 and add ens160 as a port of it. You
+will also have to flush the IP address of ens160 and restart systemd-networkd
+in the same line. It is important to let br-ens160 have the same mac address as
+ens160 to get the same IP address to br-ens160 from the DHCP server. In the
+below command, "$mac_of_ens160" holds the mac address of ens160. For e.g:
+
+```
+mac_of_ens160='"00:0c:29:77:27:7a"'
+ovs-vsctl --may-exist add-br br-ens160 -- \
+ --may-exist add-port br-ens160 ens160 -- \
+ set interface br-ens160 mac="$mac_of_ens160"; ip addr flush dev ens160; \
+ systemctl restart systemd-networkd
+```
+
+br-ens160 should now have the same DHCP IP. It should also have the correct
+DNS resolution servers configured.
+
+Notes on dependencies:
+---------------------
+
+openvswitch-switch depends on $network, $named $remote_fs and $syslog to start.
+This creates some startup dependency issues.
+
+* Since openvswitch utilities are placed in /usr and /usr can be mounted
+through NFS, openvswitch has to start after it. But if a user uses openvswitch
+for all his networking needs and hence to mount NFS, there will be a deadlock.
+So, if /usr is mounted through NFS and openvswitch is used for all networking,
+the administrator should figure out a way to mount NFS before starting OVS.
+One way to do this is in initramfs.
+
+* Since openvswitch starts after $network, $remote_fs and $syslog, any startup
+script that depends on openvswitch but starts before it, needs to be changed
+to depend on openvswitch-switch too.
+
+* Ideally, an admin should not add openvswitch bridges in the 'auto'
+section of the 'interfaces' file (i.e., if "br0" is a OVS bridge, you should
+not have a line "auto br0"). This is because, when ifupdown starts
+working on bridges listed in 'auto', openvswitch has not yet started.
+
+But, if the admin wants to go down this route and adds openvswitch bridges
+in the 'auto' section, openvswitch-switch will forcefully be started when
+ifupdown kicks in. In a case like this, the admin needs to make sure that /usr
+has already been mounted and that a remote $syslog (if used) is ready to
+receive openvswitch logs.
+
+* With systemd, adding openvswitch bridges in the 'auto' section of the
+'interfaces' file can cause race conditions (i.e., if "br0" is a OVS bridge,
+you should not have a line "auto br0"). Debian systems have added a
+systemd ifup@.service file. This file will call ifdown and ifup on interfaces
+in "auto" section automatically when the interfaces disappear and appear
+respectively. This will cause race conditions if you delete and add the same
+bridges using tools like "ovs-vsctl" or "ovs-dpctl". This is also a problem
+when you upgrade your openvswitch kernel module using commands like
+'force-reload-kmod'.