Open vSwitch <http://openvswitch.org>
-General
--------
+## Contents
+
+- [General](#general)
+- [Releases](#releases)
+- [Terminology](#terminology)
+- [Basic configuration](#basic-configuration)
+- [Implementation Details](#implementation-details)
+- [Performance](#performance)
+- [Configuration Problems](#configuration-problems)
+- [QOS](#qos)
+- [VLANs](#vlans)
+- [VXLANs](#vxlans)
+- [Using OpenFlow](#using-openflow)
+- [Development](#development)
+
+## General
### Q: What is Open vSwitch?
cannot, all the programs allow overriding the default port. See the
appropriate man page.
-
-Releases
---------
+## 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
+ process and are suitable for production use. Planned releases
+ occur twice 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
2.3.x.
+ For more information on the Open vSwitch release process, please
+ see [release-process.md].
+
### Q: What Linux kernel versions does each Open vSwitch release work with?
A: The following table lists the Linux kernel versions against which the
| 2.3.x | 2.6.32 to 3.14
| 2.4.x | 2.6.32 to 4.0
| 2.5.x | 2.6.32 to 4.3
-| 2.6.x | 3.10 to 4.3
+| 2.6.x | 3.10 to 4.7
Open vSwitch userspace should also work with the Linux kernel module
built into Linux 3.3 and later.
Linux release whose OVS module supports the feature.
* *Linux OVS tree*: The datapath implemented by the Linux kernel module
- distributed with the OVS source tree. Some features of
- this module rely on functionality not available in older
- kernels: in this case the minumum Linux version (against
- which the feature can be compiled) is listed.
+ distributed with the OVS source tree.
* *Userspace*: Also known as DPDK, dpif-netdev or dummy datapath. It is the
- only datapath that works on NetBSD and FreeBSD.
+ only datapath that works on NetBSD, FreeBSD and Mac OSX.
* *Hyper-V*: Also known as the Windows datapath.
Feature | Linux upstream | Linux OVS tree | Userspace | Hyper-V |
----------------------|:--------------:|:--------------:|:---------:|:-------:|
-Connection tracking | 4.3 | 3.10 | NO | NO |
+NAT | 4.6 | YES | NO | NO |
+Connection tracking | 4.3 | YES | PARTIAL | PARTIAL |
Tunnel - LISP | NO | YES | NO | NO |
-Tunnel - STT | NO | 3.5 | NO | YES |
+Tunnel - STT | NO | YES | NO | YES |
Tunnel - GRE | 3.11 | YES | YES | YES |
Tunnel - VXLAN | 3.12 | YES | YES | YES |
-Tunnel - Geneve | 3.18 | YES | YES | NO |
-QoS - Policing | YES | YES | NO | NO |
+Tunnel - Geneve | 3.18 | YES | YES | YES |
+Tunnel - GRE-IPv6 | NO | NO | YES | NO |
+Tunnel - VXLAN-IPv6 | 4.3 | YES | YES | NO |
+Tunnel - Geneve-IPv6 | 4.4 | YES | YES | NO |
+QoS - Policing | YES | YES | YES | NO |
QoS - Shaping | YES | YES | NO | NO |
sFlow | YES | YES | YES | NO |
+IPFIX | 3.10 | YES | YES | NO |
Set action | YES | YES | YES | PARTIAL |
NIC Bonding | YES | YES | YES | NO |
Multiple VTEPs | YES | YES | YES | NO |
Multiple datapaths | YES | YES | YES | NO |
Tunnel TSO - STT | N/A | YES | NO | YES |
+### Q: What DPDK version does each Open vSwitch release work with?
+
+A: The following table lists the DPDK version against which the
+ given versions of Open vSwitch will successfully build.
+
+| Open vSwitch | DPDK
+|:------------:|:-----:
+| 2.2.x | 1.6
+| 2.3.x | 1.6
+| 2.4.x | 2.0
+| 2.5.x | 2.2
+| 2.6.x | 16.07
+
### Q: I get an error like this when I configure Open vSwitch:
configure: error: Linux kernel in <dir> is version <x>, but
actions. On Linux kernels before 2.6.39, maximum-sized VLAN packets
may not be transmitted.
-### Q: What Linux kernel versions does IPFIX flow monitoring work with?
-
-A: IPFIX flow monitoring requires the Linux kernel module from Linux
- 3.10 or later, or the out-of-tree 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
the release. Be sure to start the ovs-brcompatd daemon.
-Terminology
------------
+## Terminology
### Q: I thought Open vSwitch was a virtual Ethernet switch, but the documentation keeps talking about bridges. What's a bridge?
A: See the "VLAN" section below.
-
-Basic Configuration
--------------------
+## Basic configuration
### Q: How do I configure a port as an access port?
A: Firstly, you must have a DPDK-enabled version of Open vSwitch.
- If your version is DPDK-enabled it will support the --dpdk
- argument on the command line and will display lines with
- "EAL:..." during startup when --dpdk is supplied.
+ If your version is DPDK-enabled it will support the other-config:dpdk-init
+ configuration in the database and will display lines with "EAL:..."
+ during startup when other_config:dpdk-init is set to 'true'.
Secondly, when adding a DPDK port, unlike a system port, the
type for the interface must be specified. For example;
Finally, it is required that DPDK port names begin with 'dpdk'.
- See [INSTALL.DPDK.md] for more information on enabling and using DPDK with
+ See [INSTALL.DPDK.rst] for more information on enabling and using DPDK with
Open vSwitch.
### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN?
### 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).
+A: No. As an alternative, Open vSwitch supports mirroring to a GRE
+ tunnel (see above).
### Q: How do I connect two bridges?
A: Open vSwitch does not support such a configuration.
Bridges always have their local ports.
-
-Implementation Details
-----------------------
+## Implementation Details
### Q: I hear OVS has a couple of kinds of flows. Can you tell me about them?
please read "The Design and Implementation of Open vSwitch",
published in USENIX NSDI 2015.
-
-Performance
------------
+## Performance
### Q: I just upgraded and I see a performance drop. Why?
userspace.
-Configuration Problems
-----------------------
+## Configuration Problems
### Q: I created a bridge and added my Ethernet port to it, using commands
like these:
for all the details.
Configuration for DPDK-enabled interfaces is slightly less
- straightforward: see [INSTALL.DPDK.md].
+ straightforward: see [INSTALL.DPDK.rst].
- Perhaps you don't actually need eth0 and eth1 to be on the
same bridge. For example, if you simply want to be able to
dmesg for errors regarding GRE registration). To fix this, unload all
GRE modules that appear in lsmod as well as the OVS kernel module. You
can then reload the OVS module following the directions in
- [INSTALL.md], which will ensure that dependencies are satisfied.
+ [INSTALL.rst], which will ensure that dependencies are satisfied.
### Q: Open vSwitch does not seem to obey my packet filter rules.
users should not configure KVM "tap" devices as type "tap" (use
type "system", the default, instead).
+### Q: I observe packet loss at the beginning of RFC2544 tests on a
+ server running few hundred container apps bridged to OVS with traffic
+ generated by HW traffic generator. How can I fix this?
+
+A: This is expected behavior on virtual switches. RFC2544 tests were
+ designed for hardware switches, which don't have caches on the fastpath
+ that need to be heated. Traffic generators in order to prime the switch
+ use learning phase to heat the caches before sending the actual traffic
+ in test phase. In case of OVS the cache is flushed quickly and to
+ accommodate the traffic generator's delay between learning and test phase,
+ the max-idle timeout settings should be changed to 50000 ms.
+
+ ovs-vsctl --no-wait set Open_vSwitch . other_config:max-idle=50000
+
+### Q: How can I configure the bridge internal interface MTU? Why does Open
+ vSwitch keep changing internal ports MTU?
+
+A: By default Open vSwitch overrides the internal interfaces (e.g. br0) MTU.
+ If you have just an internal interface (e.g. br0) and a physical interface
+ (e.g. eth0), then every change in MTU to eth0 will be reflected to br0.
+ Any manual MTU configuration using `ip` or `ifconfig` on internal interfaces
+ is going to be overridden by Open vSwitch to match the current bridge
+ minimum.
+
+ Sometimes this behavior is not desirable, for example with tunnels. The
+ MTU of an internal interface can be explicitly set using the following
+ command:
+
+ ovs-vsctl set int br0 mtu_request=1450
+
+ After this, Open vSwitch will configure br0 MTU to 1450. Since this
+ setting is in the database it will be persistent (compared to what
+ happens with `ip` or `ifconfig`).
+
+ The MTU configuration can be removed to restore the default behavior with
+
+ ovs-vsctl set int br0 mtu_request=[]
-Quality of Service (QoS)
-------------------------
+ The mtu_request column can be used to configure MTU even for physical
+ interfaces (e.g. eth0).
+
+## QOS
### Q: Does OVS support Quality of Service (QoS)?
Keep in mind that ingress and egress are from the perspective of the
switch. That means that egress shaping limits the rate at which
- traffic is allowed to transmit from a physical interface, but the
+ traffic is allowed to transmit from a physical interface, but not the
rate at which traffic will be received on a virtual machine's VIF.
For ingress policing, the behavior is the opposite.
vSwitch software switch (neither the kernel-based nor userspace
switches).
-
-VLANs
------
+## VLANs
### Q: What's a VLAN?
- Use a NIC whose driver does not have VLAN problems.
- - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later
+ - Use "VLAN splinters", a feature in Open vSwitch 1.4 upto 2.5
that works around bugs in kernel drivers. To enable VLAN
splinters on interface eth0, use the command:
for each VLANs.
-VXLANs
------
+## VXLANs
### Q: What's a VXLAN?
options:dst_port=8472
-Using OpenFlow (Manually or Via Controller)
--------------------------------------------
+## Using OpenFlow
### Q: What versions of OpenFlow does Open vSwitch support?
ovs-vsctl set bridge br0 other-config:datapath-id=0123456789abcdef
-### Q: My controller is getting errors about "buffers". What's going on?
-
-A: When a switch sends a packet to an OpenFlow controller using a
- "packet-in" message, it can also keep a copy of that packet in a
- "buffer", identified by a 32-bit integer "buffer_id". There are
- two advantages to buffering. First, when the controller wants to
- tell the switch to do something with the buffered packet (with a
- "packet-out" OpenFlow request), it does not need to send another
- copy of the packet back across the OpenFlow connection, which
- reduces the bandwidth cost of the connection and improves latency.
- This enables the second advantage: the switch can optionally send
- only the first part of the packet to the controller (assuming that
- the switch only needs to look at the first few bytes of the
- packet), further reducing bandwidth and improving latency.
-
- However, buffering introduces some issues of its own. First, any
- switch has limited resources, so if the controller does not use a
- buffered packet, the switch has to decide how long to keep it
- buffered. When many packets are sent to a controller and buffered,
- Open vSwitch can discard buffered packets that the controller has
- not used after as little as 5 seconds. This means that
- controllers, if they make use of packet buffering, should use the
- buffered packets promptly. (This includes sending a "packet-out"
- with no actions if the controller does not want to do anything with
- a buffered packet, to clear the packet buffer and effectively
- "drop" its packet.)
-
- Second, packet buffers are one-time-use, meaning that a controller
- cannot use a single packet buffer in two or more "packet-out"
- commands. Open vSwitch will respond with an error to the second
- and subsequent "packet-out"s in such a case.
-
- Finally, a common error early in controller development is to try
- to use buffer_id 0 in a "packet-out" message as if 0 represented
- "no buffered packet". This is incorrect usage: the buffer_id with
- this meaning is actually 0xffffffff.
-
- ovs-vswitchd(8) describes some details of Open vSwitch packet
- buffering that the OpenFlow specification requires implementations
- to document.
+### Q: My controller complains that OVS is not buffering packets.
+ What's going on?
+
+A: "Packet buffering" is an optional OpenFlow feature, and controllers
+ should detect how many "buffers" an OpenFlow switch implements. It
+ was recently noticed that OVS implementation of the buffering
+ feature was not compliant to OpenFlow specifications. Rather than
+ fix it and risk controller incompatibility, the buffering feature
+ is removed as of OVS 2.7. Controllers are already expected to work
+ properly in cases where the switch can not buffer packets, but
+ sends full packets in "packet-in" messages instead, so this change
+ should not affect existing users. After the change OVS always
+ sends the 'buffer_id' as 0xffffffff in "packet-in" messages and
+ will send an error response if any other value of this field is
+ included in a "packet-out" or a "flow mod" sent by a controller.
### Q: How does OVS divide flows among buckets in an OpenFlow "select" group?
vSwitch source tree. (OpenFlow 1.5 support in Open vSwitch is still
experimental.)
+### Q: I added a flow to accept packets on VLAN 123 and output them on
+ VLAN 456, like so:
+
+ ovs-ofctl add-flow br0 dl_vlan=123,actions=output:1,mod_vlan_vid:456
+
+ but the packets are actually being output in VLAN 123. Why?
+
+A: OpenFlow actions are executed in the order specified. Thus, the
+ actions above first output the packet, then change its VLAN. Since
+ the output occurs before changing the VLAN, the change in VLAN will
+ have no visible effect.
+
+ To solve this and similar problems, order actions so that changes
+ to headers happen before output, e.g.:
+
+ ovs-ofctl add-flow br0 dl_vlan=123,actions=mod_vlan_vid:456,output:1
+
+### Q: The "learn" action can't learn the action I want, can you improve it?
+
+A: By itself, the "learn" action can only put two kinds of actions
+ into the flows that it creates: "load" and "output" actions. If
+ "learn" is used in isolation, these are severe limits.
+
+ However, "learn" is not meant to be used in isolation. It is a
+ primitive meant to be used together with other Open vSwitch
+ features to accomplish a task. Its existing features are enough to
+ accomplish most tasks.
+
+ Here is an outline of a typical pipeline structure that allows for
+ versatile behavior using "learn":
+
+ - Flows in table A contain a "learn" action, that populates flows
+ in table L, that use a "load" action to populate register R
+ with information about what was learned.
+
+ - Flows in table B contain two sequential resubmit actions: one
+ to table L and another one to table B+1.
+
+ - Flows in table B+1 match on register R and act differently
+ depending on what the flows in table L loaded into it.
+
+ This approach can be used to implement many "learn"-based features.
+ For example:
+
+ - Resubmit to a table selected based on learned information, e.g. see:
+ http://openvswitch.org/pipermail/discuss/2016-June/021694.html
+
+ - MAC learning in the middle of a pipeline, as described in
+ [Tutorial.md].
+
+ - TCP state based firewalling, by learning outgoing connections
+ based on SYN packets and matching them up with incoming
+ packets.
+
+ - At least some of the features described in T. A. Hoff,
+ "Extending Open vSwitch to Facilitate Creation of Stateful SDN
+ Applications".
+
-Development
------------
+## Development
### Q: How do I implement a new OpenFlow message?
lib/ofp-msgs.h, following the existing pattern. Then recompile and
fix all of the new warnings, implementing new functionality for the
new message as needed. (If you configure with --enable-Werror, as
- described in [INSTALL.md], then it is impossible to miss any warnings.)
+ described in [INSTALL.rst], then it is impossible to miss any warnings.)
If you need to add an OpenFlow vendor extension message for a
vendor that doesn't yet have any extension messages, then you will
lib/nx-match.c to output your new field in OXM matches. Then
recompile and fix all of the new warnings, implementing new
functionality for the new field or header as needed. (If you
- configure with --enable-Werror, as described in [INSTALL.md], then
+ configure with --enable-Werror, as described in [INSTALL.rst], then
it is impossible to miss any warnings.)
If you want kernel datapath support for your new field, you also
lib/ofp-actions.c, following the existing pattern. Then recompile
and fix all of the new warnings, implementing new functionality for
the new action as needed. (If you configure with --enable-Werror,
- as described in [INSTALL.md], then it is impossible to miss any
+ as described in [INSTALL.rst], then it is impossible to miss any
warnings.)
If you need to add an OpenFlow vendor extension action for a vendor
[PORTING.md]:PORTING.md
[WHY-OVS.md]:WHY-OVS.md
-[INSTALL.md]:INSTALL.md
+[INSTALL.rst]:INSTALL.rst
[OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md
-[INSTALL.DPDK.md]:INSTALL.DPDK.md
+[INSTALL.DPDK.rst]:INSTALL.DPDK.rst
+[Tutorial.md]:tutorial/Tutorial.md
+[release-process.md]:Documentation/release-process.md
projects / mirror_ovs.git / blobdiff