[pve-devel] [PATCH docs] pve-network: add short section explaining Open vSwitch

[Christian Ebner]

Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
---
 pve-network.adoc | 140 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 139 insertions(+), 1 deletion(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index b2dae97..e8f17af 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -489,7 +489,145 @@ iface vmbr0 inet manual
 
 ----
 
+Open vSwitch
+~~~~~~~~~~~~
+
+https://www.openvswitch.org/[Open vSwitch (OVS)] is a "multilayer virtual switch
+designed to enable network automation through programmatic extension, while still
+supporting standard management interfaces and protocols". It is specifically
+tailored to function with virtualized environments.
+OVS is an alternative to Linux native bridges, bonds and VLAN interfaces and
+should never be mixed with these as this can cause problems and loss of
+connectivity.
+
+Installation
+^^^^^^^^^^^^
+
+In order to use and configure Open vSwitch (OvS) in {pve}, the
+'openvswitch-switch' package from the Proxmox VE package repositories has to be
+installed:
+
+----
+# apt-get install openvswitch-switch
+----
+
+Configuration
+^^^^^^^^^^^^^
+
+OVS configuration is easily performed via the web interface of the node under
+`System -> Network`.
+From there it is possible to create OVS brides, OVS bonds or an OVS internal
+ports.
+Advanced configuration is performed by editing `/etc/network/interfaces`,
+see the https://pve.proxmox.com/wiki/Open_vSwitch[Open vSwitch wiki page] for
+further details.
+
+OVS Bridge
+^^^^^^^^^^
+
+Just like a Linux virtual bridge, this will create a new OVS virtual bridge,
+allowing to attach raw ethernet devices and virtual interfaces such as OVS bonds
+or OVS IntPorts.
+On creation, you can directly assing raw ethernet devices to attatch to the
+bridge ports and assing an IP address to the bridge.
+In contrast to Linux virtual bridges, OVS bridges can carry multiple VLANs over
+a sinlge bridge.
+
+.Example: A simple OVS bridge setup with a single interface
+----
+allow-vmbr0 eth0
+iface eth0 inet manual
+        ovs_type OVSPort
+        ovs_bridge vmbr0
+
+auto vmbr0
+iface vmbr0 inet manual
+        ovs_type OVSBridge
+        ovs_ports eth0
+----
+
+OVS Bond
+^^^^^^^^
+
+Bonds are used to join two or more network interfaces (slaves) to act as a single
+unit in order to increase data throughput and to provide redundancy in case one
+of the links fails. Bonds must refer to raw ethernet devices (for example eth0,
+eth1).
+
+The following bond modes can be set in the web interface:
+
+* active-backup: This will configure an active/standby failover mode. All of the
+traffic is send over the active interface as long as it is available, on failure
+the standby interface is used.
+
+* balance-slb: Source load balancing or SLB bonding will divide traffic based on
+the ethernet source address and VLAN tag. It assigns each source MAC+VLAN to a
+link.
+
+* LACP (balance-slb): This will configure balance-slb with LACP set to active.
+
+* LACP (balance-tcp): This will perform load balancing with layer 2 to layer 4
+data taken into consideration with LACP set to active.
+
+NOTE: The use of LACP for link aggregation is recommended when creating a bond, but
+requires the switch on the other end to support this.
+
+For further details refere to the
+http://docs.openvswitch.org/en/latest/topics/bonding/[corresponding section in
+the Open vSwitch documentation.]
+
+.Example: A simple OVS bond configuration
+----
+allow-vmbr0 bond0
+iface bond0 inet manual
+    ovs_bonds eth0 eth1
+    ovs_type OVSBond
+    ovs_bridge vmbr0
+    ovs_options bond_mode=balance-tcp lacp=active
+
+auto vmbr0
+iface vmbr0 inet manual
+        ovs_type OVSBridge
+        ovs_ports bond0
+----
+
+OVS IntPort
+^^^^^^^^^^^
+
+The creation of an OVS IntPort is neccessary in order for the host to connect to 
+a VLAN on the bridge.
+This creates a virtual interface for the specified VLAN to which then an IP
+address can be assigned.
+The so created ports must also show up in the corresponding bridge definition and
+have to be prefixed with the `allow-$bridge $iface`.
+
+.Example: A OVS IntPort with assigned IP address
+----
+allow-vmbr0 bond0
+iface bond0 inet manual
+    ovs_bonds eth0 eth1
+    ovs_type OVSBond
+    ovs_bridge vmbr0
+    ovs_options tag=10 bond_mode=balance-tcp lacp=active
+
+allow-vmbr0 vlan10
+iface vlan10 inet static
+    address 10.0.0.10
+    netmask 24
+    ovs_type OVSIntPort
+    ovs_bridge vmbr0
+    ovs_options tag=10
+
+auto vmbr0
+iface vmbr0 inet manual
+        ovs_type OVSBridge
+        ovs_ports bond0 vlan10
+----
+
+For further details see http://docs.openvswitch.org/en/latest/[the Open vSwitch documentation] and 
+the https://pve.proxmox.com/wiki/Open_vSwitch[Open vSwitch wiki page].
+
 ////
 TODO: explain IPv6 support?
-TODO: explain OVS
+
 ////
-- 
2.20.1