Merge branch 'mainstream'
[sliver-openvswitch.git] / FAQ
diff --git a/FAQ b/FAQ
index 810803e..cd3241a 100644 (file)
--- a/FAQ
+++ b/FAQ
@@ -27,7 +27,7 @@ A: Open vSwitch is a production quality open source software switch
 Q: What virtualization platforms can use Open vSwitch?
 
 A: Open vSwitch can currently run on any Linux-based virtualization
-   platform (kernel 2.6.18 and newer), including: KVM, VirtualBox, Xen,
+   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
@@ -89,10 +89,9 @@ A: Distributed vswitch applications (e.g., VMware vNetwork distributed
    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.
+   includes tools (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?
 
@@ -148,13 +147,14 @@ A: The following table lists the Linux kernel versions against which the
        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
-       1.12.x     2.6.18 to 3.9
+       2.0.x      2.6.32 to 3.10
+       2.1.x      2.6.32 to 3.11
 
    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.18
+   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?
@@ -168,7 +168,7 @@ Q: Should userspace or kernel be upgraded first to minimize downtime?
    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.
+   the possibility of incompatibilities.
 
 Q: What features are not available in the Open vSwitch kernel datapath
    that ships as part of the upstream Linux kernel?
@@ -197,6 +197,25 @@ A: Tunnel virtual ports are not supported, as described in the
    actions.  On Linux kernels before 2.6.39, maximum-sized VLAN packets
    may not be transmitted.
 
+Q: What happened to the bridge compatibility feature?
+
+A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier.
+   When it was enabled, Open vSwitch imitated the interface of the
+   Linux kernel "bridge" module.  This allowed users to drop Open
+   vSwitch into environments designed to use the Linux kernel bridge
+   module without adapting the environment to use Open vSwitch.
+
+   Open vSwitch 1.10 and later do not support bridge compatibility.
+   The feature was dropped because version 1.10 adopted a new internal
+   architecture that made bridge compatibility difficult to maintain.
+   Now that many environments use OVS directly, it would be rarely
+   useful in any case.
+
+   To use bridge compatibility, install OVS 1.9 or earlier, including
+   the accompanying kernel modules (both the main and bridge
+   compatibility modules), following the instructions that come with
+   the release.  Be sure to start the ovs-brcompatd daemon.
+
 
 Terminology
 -----------
@@ -250,6 +269,40 @@ A: The following commands configure br0 with eth0 and tap0 as trunk
 
        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?
 
@@ -1201,9 +1254,11 @@ A: To debug network behavior problems, trace the path of a packet,
 
 Q: How do I make a flow drop packets?
 
-A: An empty set of actions causes a packet to be dropped.  You can
-   specify an empty set of actions with "actions=" on the ovs-ofctl
-   command line.  For example:
+A: To drop a packet is to receive it without forwarding it.  OpenFlow
+   explicitly specifies forwarding actions.  Thus, a flow with an
+   empty set of actions does not forward packets anywhere, causing
+   them to be dropped.  You can specify an empty set of actions with
+   "actions=" on the ovs-ofctl command line.  For example:
 
        ovs-ofctl add-flow br0 priority=65535,actions=
 
@@ -1215,6 +1270,92 @@ A: An empty set of actions causes a packet to be dropped.  You can
 
        ovs-ofctl add-flow br0 priority=65535,actions=drop
 
+   "drop" is not an action, either in OpenFlow or Open vSwitch.
+   Rather, it is only a way to say that there are no actions.
+
+Q: I added a flow to send packets out the ingress port, like this:
+
+       ovs-ofctl add-flow br0 in_port=2,actions=2
+
+   but OVS drops the packets instead.
+
+A: Yes, OpenFlow requires a switch to ignore attempts to send a packet
+   out its ingress port.  The rationale is that dropping these packets
+   makes it harder to loop the network.  Sometimes this behavior can
+   even be convenient, e.g. it is often the desired behavior in a flow
+   that forwards a packet to several ports ("floods" the packet).
+
+   Sometimes one really needs to send a packet out its ingress port.
+   In this case, output to OFPP_IN_PORT, which in ovs-ofctl syntax is
+   expressed as just "in_port", e.g.:
+
+       ovs-ofctl add-flow br0 in_port=2,actions=in_port
+
+   This also works in some circumstances where the flow doesn't match
+   on the input port.  For example, if you know that your switch has
+   five ports numbered 2 through 6, then the following will send every
+   received packet out every port, even its ingress port:
+
+       ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
+
+   or, equivalently:
+
+       ovs-ofctl add-flow br0 actions=all,in_port
+
+   Sometimes, in complicated flow tables with multiple levels of
+   "resubmit" actions, a flow needs to output to a particular port
+   that may or may not be the ingress port.  It's difficult to take
+   advantage of OFPP_IN_PORT in this situation.  To help, Open vSwitch
+   provides, as an OpenFlow extension, the ability to modify the
+   in_port field.  Whatever value is currently in the in_port field is
+   the port to which outputs will be dropped, as well as the
+   destination for OFPP_IN_PORT.  This means that the following will
+   reliably output to port 2 or to ports 2 through 6, respectively:
+
+       ovs-ofctl add-flow br0 in_port=2,actions=load:0->NXM_OF_IN_PORT[],2
+       ovs-ofctl add-flow br0 actions=load:0->NXM_OF_IN_PORT[],2,3,4,5,6
+
+   If the input port is important, then one may save and restore it on
+   the stack:
+
+        ovs-ofctl add-flow br0 actions=push:NXM_OF_IN_PORT[],\
+                                       load:0->NXM_OF_IN_PORT[],\
+                                       2,3,4,5,6,\
+                                       pop:NXM_OF_IN_PORT[]
+
+Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2
+   on port 2.  I set up flows to forward only traffic destined to the
+   other host and drop other traffic, like this:
+
+      priority=5,in_port=1,ip,nw_dst=192.168.0.2,actions=2
+      priority=5,in_port=2,ip,nw_dst=192.168.0.1,actions=1
+      priority=0,actions=drop
+
+   But it doesn't work--I don't get any connectivity when I do this.
+   Why?
+
+A: These flows drop the ARP packets that IP hosts use to establish IP
+   connectivity over Ethernet.  To solve the problem, add flows to
+   allow ARP to pass between the hosts:
+
+      priority=5,in_port=1,arp,actions=2
+      priority=5,in_port=2,arp,actions=1
+
+   This issue can manifest other ways, too.  The following flows that
+   match on Ethernet addresses instead of IP addresses will also drop
+   ARP packets, because ARP requests are broadcast instead of being
+   directed to a specific host:
+
+      priority=5,in_port=1,dl_dst=54:00:00:00:00:02,actions=2
+      priority=5,in_port=2,dl_dst=54:00:00:00:00:01,actions=1
+      priority=0,actions=drop
+
+   The solution already described above will also work in this case.
+   It may be better to add flows to allow all multicast and broadcast
+   traffic:
+
+      priority=5,in_port=1,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=2
+      priority=5,in_port=2,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=1
 
 Contact 
 -------