+General
+-------
+
+Q: What is Open vSwitch?
+
+A: Open vSwitch is a production quality open source software switch
+ designed to be used as a vswitch in virtualized server
+ environments. A vswitch forwards traffic between different VMs on
+ the same physical host and also forwards traffic between VMs and
+ the physical network. Open vSwitch supports standard management
+ interfaces (e.g. sFlow, NetFlow, IPFIX, RSPAN, CLI), and is open to
+ programmatic extension and control using OpenFlow and the OVSDB
+ management protocol.
+
+ Open vSwitch as designed to be compatible with modern switching
+ chipsets. This means that it can be ported to existing high-fanout
+ switches allowing the same flexible control of the physical
+ infrastructure as the virtual infrastructure. It also means that
+ Open vSwitch will be able to take advantage of on-NIC switching
+ chipsets as their functionality matures.
+
+Q: What virtualization platforms can use Open vSwitch?
+
+A: Open vSwitch can currently run on any Linux-based virtualization
+ platform (kernel 2.6.32 and newer), including: KVM, VirtualBox, Xen,
+ Xen Cloud Platform, XenServer. As of Linux 3.3 it is part of the
+ mainline kernel. The bulk of the code is written in platform-
+ independent C and is easily ported to other environments. We welcome
+ inquires about integrating Open vSwitch with other virtualization
+ platforms.
+
+Q: How can I try Open vSwitch?
+
+A: The Open vSwitch source code can be built on a Linux system. You can
+ build and experiment with Open vSwitch on any Linux machine.
+ Packages for various Linux distributions are available on many
+ platforms, including: Debian, Ubuntu, Fedora.
+
+ You may also download and run a virtualization platform that already
+ has Open vSwitch integrated. For example, download a recent ISO for
+ XenServer or Xen Cloud Platform. Be aware that the version
+ integrated with a particular platform may not be the most recent Open
+ vSwitch release.
+
+Q: Does Open vSwitch only work on Linux?
+
+A: No, Open vSwitch has been ported to a number of different operating
+ systems and hardware platforms. Most of the development work occurs
+ on Linux, but the code should be portable to any POSIX system. We've
+ seen Open vSwitch ported to a number of different platforms,
+ including FreeBSD, Windows, and even non-POSIX embedded systems.
+
+ By definition, the Open vSwitch Linux kernel module only works on
+ Linux and will provide the highest performance. However, a userspace
+ datapath is available that should be very portable.
+
+Q: What's involved with porting Open vSwitch to a new platform or
+ switching ASIC?
+
+A: The PORTING document describes how one would go about porting Open
+ vSwitch to a new operating system or hardware platform.
+
+Q: Why would I use Open vSwitch instead of the Linux bridge?
+
+A: Open vSwitch is specially designed to make it easier to manage VM
+ network configuration and monitor state spread across many physical
+ hosts in dynamic virtualized environments. Please see WHY-OVS for a
+ more detailed description of how Open vSwitch relates to the Linux
+ Bridge.
+
+Q: How is Open vSwitch related to distributed virtual switches like the
+ VMware vNetwork distributed switch or the Cisco Nexus 1000V?
+
+A: Distributed vswitch applications (e.g., VMware vNetwork distributed
+ switch, Cisco Nexus 1000V) provide a centralized way to configure and
+ monitor the network state of VMs that are spread across many physical
+ hosts. Open vSwitch is not a distributed vswitch itself, rather it
+ runs on each physical host and supports remote management in a way
+ that makes it easier for developers of virtualization/cloud
+ management platforms to offer distributed vswitch capabilities.
+
+ To aid in distribution, Open vSwitch provides two open protocols that
+ are specially designed for remote management in virtualized network
+ environments: OpenFlow, which exposes flow-based forwarding state,
+ and the OVSDB management protocol, which exposes switch port state.
+ In addition to the switch implementation itself, Open vSwitch
+ includes tools (ovs-controller, ovs-ofctl, ovs-vsctl) that developers
+ can script and extend to provide distributed vswitch capabilities
+ that are closely integrated with their virtualization management
+ platform.
+
+Q: Why doesn't Open vSwitch support distribution?
+
+A: Open vSwitch is intended to be a useful component for building
+ flexible network infrastructure. There are many different approaches
+ to distribution which balance trade-offs between simplicity,
+ scalability, hardware compatibility, convergence times, logical
+ forwarding model, etc. The goal of Open vSwitch is to be able to
+ support all as a primitive building block rather than choose a
+ particular point in the distributed design space.
+
+Q: How can I contribute to the Open vSwitch Community?
+
+A: You can start by joining the mailing lists and helping to answer
+ questions. You can also suggest improvements to documentation. If
+ you have a feature or bug you would like to work on, send a mail to
+ one of the mailing lists:
+
+ http://openvswitch.org/mlists/
+
+
+Releases
+--------
+
+Q: What does it mean for an Open vSwitch release to be LTS (long-term
+ support)?
+
+A: All official releases have been through a comprehensive testing
+ process and are suitable for production use. Planned releases will
+ occur several times a year. If a significant bug is identified in an
+ LTS release, we will provide an updated release that includes the
+ fix. Releases that are not LTS may not be fixed and may just be
+ supplanted by the next major release. The current LTS release is
+ 1.9.x.
+
+Q: What Linux kernel versions does each Open vSwitch release work with?
+
+A: The following table lists the Linux kernel versions against which the
+ given versions of the Open vSwitch kernel module will successfully
+ build. The Linux kernel versions are upstream kernel versions, so
+ Linux kernels modified from the upstream sources may not build in
+ some cases even if they are based on a supported version. This is
+ most notably true of Red Hat Enterprise Linux (RHEL) kernels, which
+ are extensively modified from upstream.
+
+ Open vSwitch Linux kernel
+ ------------ -------------
+ 1.4.x 2.6.18 to 3.2
+ 1.5.x 2.6.18 to 3.2
+ 1.6.x 2.6.18 to 3.2
+ 1.7.x 2.6.18 to 3.3
+ 1.8.x 2.6.18 to 3.4
+ 1.9.x 2.6.18 to 3.8
+ 1.10.x 2.6.18 to 3.8
+ 1.11.x 2.6.18 to 3.8
+ 2.0.x 2.6.32 to 3.10
+
+ Open vSwitch userspace should also work with the Linux kernel module
+ built into Linux 3.3 and later.
+
+ Open vSwitch userspace is not sensitive to the Linux kernel version.
+ It should build against almost any kernel, certainly against 2.6.32
+ and later.
+
+Q: What Linux kernel versions does IPFIX flow monitoring work with?
+
+A: IPFIX flow monitoring requires the Linux kernel module from Open
+ vSwitch version 1.10.90 or later.
+
+Q: Should userspace or kernel be upgraded first to minimize downtime?
+
+ In general, the Open vSwitch userspace should be used with the
+ kernel version included in the same release or with the version
+ from upstream Linux. However, when upgrading between two releases
+ of Open vSwitch it is best to migrate userspace first to reduce
+ the possbility of incompatibilities.
+
+Q: What features are not available in the Open vSwitch kernel datapath
+ that ships as part of the upstream Linux kernel?
+
+A: The kernel module in upstream Linux 3.3 and later does not include
+ tunnel virtual ports, that is, interfaces with type "gre",
+ "ipsec_gre", "gre64", "ipsec_gre64", "vxlan", or "lisp". It is
+ possible to create tunnels in Linux and attach them to Open vSwitch
+ as system devices. However, they cannot be dynamically created
+ through the OVSDB protocol or set the tunnel ids as a flow action.
+
+ Work is in progress in adding tunnel virtual ports to the upstream
+ Linux version of the Open vSwitch kernel module. For now, if you
+ need these features, use the kernel module from the Open vSwitch
+ distribution instead of the upstream Linux kernel module.
+
+ The upstream kernel module does not include patch ports, but this
+ only matters for Open vSwitch 1.9 and earlier, because Open vSwitch
+ 1.10 and later implement patch ports without using this kernel
+ feature.
+
+Q: What features are not available when using the userspace datapath?
+
+A: Tunnel virtual ports are not supported, as described in the
+ previous answer. It is also not possible to use queue-related
+ actions. On Linux kernels before 2.6.39, maximum-sized VLAN packets
+ may not be transmitted.
+
+
+Terminology
+-----------
+
+Q: I thought Open vSwitch was a virtual Ethernet switch, but the
+ documentation keeps talking about bridges. What's a bridge?
+
+A: In networking, the terms "bridge" and "switch" are synonyms. Open
+ vSwitch implements an Ethernet switch, which means that it is also
+ an Ethernet bridge.
+
+Q: What's a VLAN?
+
+A: See the "VLAN" section below.
+
+
+Basic Configuration
+-------------------
+
+Q: How do I configure a port as an access port?
+
+A: Add "tag=VLAN" to your "ovs-vsctl add-port" command. For example,
+ the following commands configure br0 with eth0 as a trunk port (the
+ default) and tap0 as an access port for VLAN 9:
+
+ ovs-vsctl add-br br0
+ ovs-vsctl add-port br0 eth0
+ ovs-vsctl add-port br0 tap0 tag=9
+
+ If you want to configure an already added port as an access port,
+ use "ovs-vsctl set", e.g.:
+
+ ovs-vsctl set port tap0 tag=9
+
+Q: How do I configure a port as a SPAN port, that is, enable mirroring
+ of all traffic to that port?
+
+A: The following commands configure br0 with eth0 and tap0 as trunk
+ ports. All traffic coming in or going out on eth0 or tap0 is also
+ mirrored to tap1; any traffic arriving on tap1 is dropped:
+
+ ovs-vsctl add-br br0
+ ovs-vsctl add-port br0 eth0
+ ovs-vsctl add-port br0 tap0
+ ovs-vsctl add-port br0 tap1 \
+ -- --id=@p get port tap1 \
+ -- --id=@m create mirror name=m0 select-all=true output-port=@p \
+ -- set bridge br0 mirrors=@m
+
+ To later disable mirroring, run:
+
+ ovs-vsctl clear bridge br0 mirrors
+
+Q: Does Open vSwitch support configuring a port in promiscuous mode?
+
+A: Yes. How you configure it depends on what you mean by "promiscuous
+ mode":
+
+ - Conventionally, "promiscuous mode" is a feature of a network
+ interface card. Ordinarily, a NIC passes to the CPU only the
+ packets actually destined to its host machine. It discards
+ the rest to avoid wasting memory and CPU cycles. When
+ promiscuous mode is enabled, however, it passes every packet
+ to the CPU. On an old-style shared-media or hub-based
+ network, this allows the host to spy on all packets on the
+ network. But in the switched networks that are almost
+ everywhere these days, promiscuous mode doesn't have much
+ effect, because few packets not destined to a host are
+ delivered to the host's NIC.
+
+ This form of promiscuous mode is configured in the guest OS of
+ the VMs on your bridge, e.g. with "ifconfig".
+
+ - The VMware vSwitch uses a different definition of "promiscuous
+ mode". When you configure promiscuous mode on a VMware vNIC,
+ the vSwitch sends a copy of every packet received by the
+ vSwitch to that vNIC. That has a much bigger effect than just
+ enabling promiscuous mode in a guest OS. Rather than getting
+ a few stray packets for which the switch does not yet know the
+ correct destination, the vNIC gets every packet. The effect
+ is similar to replacing the vSwitch by a virtual hub.
+
+ This "promiscuous mode" is what switches normally call "port
+ mirroring" or "SPAN". For information on how to configure
+ SPAN, see "How do I configure a port as a SPAN port, that is,
+ enable mirroring of all traffic to that port?"
+
+Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable
+ mirroring of all traffic to that VLAN?
+
+A: The following commands configure br0 with eth0 as a trunk port and
+ tap0 as an access port for VLAN 10. All traffic coming in or going
+ out on tap0, as well as traffic coming in or going out on eth0 in
+ VLAN 10, is also mirrored to VLAN 15 on eth0. The original tag for
+ VLAN 10, in cases where one is present, is dropped as part of
+ mirroring:
+
+ ovs-vsctl add-br br0
+ ovs-vsctl add-port br0 eth0
+ ovs-vsctl add-port br0 tap0 tag=10
+ ovs-vsctl \
+ -- --id=@m create mirror name=m0 select-all=true select-vlan=10 \
+ output-vlan=15 \
+ -- set bridge br0 mirrors=@m
+
+ To later disable mirroring, run:
+
+ ovs-vsctl clear bridge br0 mirrors
+
+ Mirroring to a VLAN can disrupt a network that contains unmanaged
+ switches. See ovs-vswitchd.conf.db(5) for details. Mirroring to a
+ GRE tunnel has fewer caveats than mirroring to a VLAN and should
+ generally be preferred.
+
+Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
+
+A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor
+ of the specified output-vlan. This loss of information may make
+ the mirrored traffic too hard to interpret.
+
+ To mirror multiple VLANs, use the commands above, but specify a
+ comma-separated list of VLANs as the value for select-vlan. To
+ mirror every VLAN, use the commands above, but omit select-vlan and
+ its value entirely.
+
+ When a packet arrives on a VLAN that is used as a mirror output
+ VLAN, the mirror is disregarded. Instead, in standalone mode, OVS
+ floods the packet across all the ports for which the mirror output
+ VLAN is configured. (If an OpenFlow controller is in use, then it
+ can override this behavior through the flow table.) If OVS is used
+ as an intermediate switch, rather than an edge switch, this ensures
+ that the RSPAN traffic is distributed through the network.
+
+ Mirroring to a VLAN can disrupt a network that contains unmanaged
+ switches. See ovs-vswitchd.conf.db(5) for details. Mirroring to a
+ GRE tunnel has fewer caveats than mirroring to a VLAN and should
+ generally be preferred.
+
+Q: How do I configure mirroring of all traffic to a GRE tunnel?
+
+A: The following commands configure br0 with eth0 and tap0 as trunk
+ ports. All traffic coming in or going out on eth0 or tap0 is also
+ mirrored to gre0, a GRE tunnel to the remote host 192.168.1.10; any
+ traffic arriving on gre0 is dropped:
+
+ ovs-vsctl add-br br0
+ ovs-vsctl add-port br0 eth0
+ ovs-vsctl add-port br0 tap0
+ ovs-vsctl add-port br0 gre0 \
+ -- set interface gre0 type=gre options:remote_ip=192.168.1.10 \
+ -- --id=@p get port gre0 \
+ -- --id=@m create mirror name=m0 select-all=true output-port=@p \
+ -- set bridge br0 mirrors=@m
+
+ To later disable mirroring and destroy the GRE tunnel:
+
+ ovs-vsctl clear bridge br0 mirrors
+ ovs-vcstl del-port br0 gre0
+
+Q: Does Open vSwitch support ERSPAN?
+
+A: No. ERSPAN is an undocumented proprietary protocol. As an
+ alternative, Open vSwitch supports mirroring to a GRE tunnel (see
+ above).
+
+Q: How do I connect two bridges?
+
+A: First, why do you want to do this? Two connected bridges are not
+ much different from a single bridge, so you might as well just have
+ a single bridge with all your ports on it.
+
+ If you still want to connect two bridges, you can use a pair of
+ patch ports. The following example creates bridges br0 and br1,
+ adds eth0 and tap0 to br0, adds tap1 to br1, and then connects br0
+ and br1 with a pair of patch ports.
+
+ ovs-vsctl add-br br0
+ ovs-vsctl add-port br0 eth0
+ ovs-vsctl add-port br0 tap0
+ ovs-vsctl add-br br1
+ ovs-vsctl add-port br1 tap1
+ ovs-vsctl \
+ -- add-port br0 patch0 \
+ -- set interface patch0 type=patch options:peer=patch1 \
+ -- add-port br1 patch1 \
+ -- set interface patch1 type=patch options:peer=patch0
+
+ Bridges connected with patch ports are much like a single bridge.
+ For instance, if the example above also added eth1 to br1, and both
+ eth0 and eth1 happened to be connected to the same next-hop switch,
+ then you could loop your network just as you would if you added
+ eth0 and eth1 to the same bridge (see the "Configuration Problems"
+ section below for more information).
+
+ If you are using Open vSwitch 1.9 or an earlier version, then you
+ need to be using the kernel module bundled with Open vSwitch rather
+ than the one that is integrated into Linux 3.3 and later, because
+ Open vSwitch 1.9 and earlier versions need kernel support for patch
+ ports. This also means that in Open vSwitch 1.9 and earlier, patch
+ ports will not work with the userspace datapath, only with the
+ kernel module.
+
+Q: Why are there so many different ways to dump flows?
+
+A: Open vSwitch uses different kinds of flows for different purposes:
+
+ - OpenFlow flows are the most important kind of flow. OpenFlow
+ controllers use these flows to define a switch's policy.
+ OpenFlow flows support wildcards, priorities, and multiple
+ tables.
+
+ When in-band control is in use, Open vSwitch sets up a few
+ "hidden" flows, with priority higher than a controller or the
+ user can configure, that are not visible via OpenFlow. (See
+ the "Controller" section of the FAQ for more information
+ about hidden flows.)
+
+ - The Open vSwitch software switch implementation uses a second
+ kind of flow internally. These flows, called "exact-match"
+ or "datapath" or "kernel" flows, do not support wildcards or
+ priorities and comprise only a single table, which makes them
+ suitable for caching. OpenFlow flows and exact-match flows
+ also support different actions and number ports differently.
+
+ Exact-match flows are an implementation detail that is
+ subject to change in future versions of Open vSwitch. Even
+ with the current version of Open vSwitch, hardware switch
+ implementations do not necessarily use exact-match flows.
+
+ Each of the commands for dumping flows has a different purpose:
+
+ - "ovs-ofctl dump-flows <br>" dumps OpenFlow flows, excluding
+ hidden flows. This is the most commonly useful form of flow
+ dump. (Unlike the other commands, this should work with any
+ OpenFlow switch, not just Open vSwitch.)
+
+ - "ovs-appctl bridge/dump-flows <br>" dumps OpenFlow flows,
+ including hidden flows. This is occasionally useful for
+ troubleshooting suspected issues with in-band control.
+
+ - "ovs-dpctl dump-flows [dp]" dumps the exact-match flow table
+ entries for a Linux kernel-based datapath. In Open vSwitch
+ 1.10 and later, ovs-vswitchd merges multiple switches into a
+ single datapath, so it will show all the flows on all your
+ kernel-based switches. This command can occasionally be
+ useful for debugging.
+
+ - "ovs-appctl dpif/dump-flows <br>", new in Open vSwitch 1.10,
+ dumps exact-match flows for only the specified bridge,
+ regardless of the type.
+
+