doc: Populate 'faq' section

This is mostly the exact same contents, albeit broken up into multiple
files.

Signed-off-by: Stephen Finucane <[email protected]>
Signed-off-by: Ben Pfaff <[email protected]>

Documentation/automake.mk

@@ -46,6 +46,17 @@ EXTRA_DIST += \
 	Documentation/howto/vtep.rst \
 	Documentation/ref/index.rst \
 	Documentation/faq/index.rst \
+	Documentation/faq/configuration.rst \
+	Documentation/faq/contributing.rst \
+	Documentation/faq/design.rst \
+	Documentation/faq/general.rst \
+	Documentation/faq/issues.rst \
+	Documentation/faq/openflow.rst \
+	Documentation/faq/qos.rst \
+	Documentation/faq/releases.rst \
+	Documentation/faq/terminology.rst \
+	Documentation/faq/vlan.rst \
+	Documentation/faq/vxlan.rst \
 	Documentation/internals/index.rst \
 	Documentation/internals/authors.rst \
 	Documentation/internals/bugs.rst \

Documentation/faq/configuration.rst

@@ -0,0 +1,240 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+===================
+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 DPDK 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 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::
+
+        $ ovs-vsctl add-br br0
+        $ ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk
+
+    Finally, it is required that DPDK port names begin with ``dpdk``.
+
+    Refer to :doc:`/intro/install/dpdk` 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?
+
+    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-vsctl del-port br0 gre0
+
+Q: Does Open vSwitch support ERSPAN?
+
+    A: No.  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: How do I configure a bridge without an OpenFlow local port?  (Local port in
+the sense of OFPP_LOCAL)
+
+    A: Open vSwitch does not support such a configuration.  Bridges always have
+    their local ports.

Documentation/faq/contributing.rst

@@ -0,0 +1,75 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+===========
+Development
+===========
+
+Q: How do I implement a new OpenFlow message?
+
+    A: Add your new message to ``enum ofpraw`` and ``enum ofptype`` in
+    ``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
+    :doc:`/intro/install/general`, 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 also need to edit
+    ``build-aux/extract-ofp-msgs``.
+
+Q: How do I add support for a new field or header?
+
+    A: Add new members for your field to ``struct flow`` in ``lib/flow.h``, and
+    add new enumerations for your new field to ``enum mf_field_id`` in
+    ``lib/meta-flow.h``, following the existing pattern.  Also, add support to
+    ``miniflow_extract()`` in ``lib/flow.c`` for extracting your new field from
+    a packet into struct miniflow, and to ``nx_put_raw()`` in
+    ``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 :doc:`/intro/install/general`, then it is impossible to miss
+    any warnings.)
+
+    If you want kernel datapath support for your new field, you also need to
+    modify the kernel module for the operating systems you are interested in.
+    This isn't mandatory, since fields understood only by userspace work too
+    (with a performance penalty), so it's reasonable to start development
+    without it.  If you implement kernel module support for Linux, then the
+    Linux kernel "netdev" mailing list is the place to submit that support
+    first; please read up on the Linux kernel development process separately.
+    The Windows datapath kernel module support, on the other hand, is
+    maintained within the OVS tree, so patches for that can go directly to
+    ovs-dev.
+
+Q: How do I add support for a new OpenFlow action?
+
+    A: Add your new action to ``enum ofp_raw_action_type`` in
+    ``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 the :doc:`/intro/install/general`, then it is impossible to miss any
+    warnings.)
+
+    If you need to add an OpenFlow vendor extension action for a vendor that
+    doesn't yet have any extension actions, then you will also need to edit
+    ``build-aux/extract-ofp-actions``.