FAQ.md

   1 Frequently Asked Questions
   2 ==========================
   3
   4 Open vSwitch <http://openvswitch.org>
   5
   6 General
   7 -------
   8
   9 ### Q: What is Open vSwitch?
  10
  11 A: Open vSwitch is a production quality open source software switch
  12    designed to be used as a vswitch in virtualized server
  13    environments.  A vswitch forwards traffic between different VMs on
  14    the same physical host and also forwards traffic between VMs and
  15    the physical network.  Open vSwitch supports standard management
  16    interfaces (e.g. sFlow, NetFlow, IPFIX, RSPAN, CLI), and is open to
  17    programmatic extension and control using OpenFlow and the OVSDB
  18    management protocol.
  19
  20    Open vSwitch as designed to be compatible with modern switching
  21    chipsets.  This means that it can be ported to existing high-fanout
  22    switches allowing the same flexible control of the physical
  23    infrastructure as the virtual infrastructure.  It also means that
  24    Open vSwitch will be able to take advantage of on-NIC switching
  25    chipsets as their functionality matures.
  26
  27 ### Q: What virtualization platforms can use Open vSwitch?
  28
  29 A: Open vSwitch can currently run on any Linux-based virtualization
  30    platform (kernel 2.6.32 and newer), including: KVM, VirtualBox, Xen,
  31    Xen Cloud Platform, XenServer. As of Linux 3.3 it is part of the
  32    mainline kernel.  The bulk of the code is written in platform-
  33    independent C and is easily ported to other environments.  We welcome
  34    inquires about integrating Open vSwitch with other virtualization
  35    platforms.
  36
  37 ### Q: How can I try Open vSwitch?
  38
  39 A: The Open vSwitch source code can be built on a Linux system.  You can
  40    build and experiment with Open vSwitch on any Linux machine.
  41    Packages for various Linux distributions are available on many
  42    platforms, including: Debian, Ubuntu, Fedora.
  43
  44    You may also download and run a virtualization platform that already
  45    has Open vSwitch integrated.  For example, download a recent ISO for
  46    XenServer or Xen Cloud Platform.  Be aware that the version
  47    integrated with a particular platform may not be the most recent Open
  48    vSwitch release.
  49
  50 ### Q: Does Open vSwitch only work on Linux?
  51
  52 A: No, Open vSwitch has been ported to a number of different operating
  53    systems and hardware platforms.  Most of the development work occurs
  54    on Linux, but the code should be portable to any POSIX system.  We've
  55    seen Open vSwitch ported to a number of different platforms,
  56    including FreeBSD, Windows, and even non-POSIX embedded systems.
  57
  58    By definition, the Open vSwitch Linux kernel module only works on
  59    Linux and will provide the highest performance.  However, a userspace
  60    datapath is available that should be very portable.
  61
  62 ### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC?
  63
  64 A: The [PORTING.md] document describes how one would go about
  65    porting Open vSwitch to a new operating system or hardware platform.
  66
  67 ### Q: Why would I use Open vSwitch instead of the Linux bridge?
  68
  69 A: Open vSwitch is specially designed to make it easier to manage VM
  70    network configuration and monitor state spread across many physical
  71    hosts in dynamic virtualized environments.  Please see
  72    [WHY-OVS.md] for a more detailed description of how Open vSwitch
  73    relates to the Linux Bridge.
  74
  75 ### Q: How is Open vSwitch related to distributed virtual switches like the VMware vNetwork distributed switch or the Cisco Nexus 1000V?
  76
  77 A: Distributed vswitch applications (e.g., VMware vNetwork distributed
  78    switch, Cisco Nexus 1000V) provide a centralized way to configure and
  79    monitor the network state of VMs that are spread across many physical
  80    hosts.  Open vSwitch is not a distributed vswitch itself, rather it
  81    runs on each physical host and supports remote management in a way
  82    that makes it easier for developers of virtualization/cloud
  83    management platforms to offer distributed vswitch capabilities.
  84
  85    To aid in distribution, Open vSwitch provides two open protocols that
  86    are specially designed for remote management in virtualized network
  87    environments: OpenFlow, which exposes flow-based forwarding state,
  88    and the OVSDB management protocol, which exposes switch port state.
  89    In addition to the switch implementation itself, Open vSwitch
  90    includes tools (ovs-ofctl, ovs-vsctl) that developers can script and
  91    extend to provide distributed vswitch capabilities that are closely
  92    integrated with their virtualization management platform.
  93
  94 ### Q: Why doesn't Open vSwitch support distribution?
  95
  96 A: Open vSwitch is intended to be a useful component for building
  97    flexible network infrastructure. There are many different approaches
  98    to distribution which balance trade-offs between simplicity,
  99    scalability, hardware compatibility, convergence times, logical
 100    forwarding model, etc. The goal of Open vSwitch is to be able to
 101    support all as a primitive building block rather than choose a
 102    particular point in the distributed design space.
 103
 104 ### Q: How can I contribute to the Open vSwitch Community?
 105
 106 A: You can start by joining the mailing lists and helping to answer
 107    questions.  You can also suggest improvements to documentation.  If
 108    you have a feature or bug you would like to work on, send a mail to
 109    one of the mailing lists:
 110
 111    http://openvswitch.org/mlists/
 112
 113 ### Q: Why can I no longer connect to my OpenFlow controller or OVSDB
 114 manager?
 115
 116 A: Starting in OVS 2.4, we switched the default ports to the
 117    IANA-specified port numbers for OpenFlow (6633->6653) and OVSDB
 118    (6632->6640).  We recommend using these port numbers, but if you
 119    cannot, all the programs allow overriding the default port.  See the
 120    appropriate man page.
 121
 122
 123 Releases
 124 --------
 125
 126 ### Q: What does it mean for an Open vSwitch release to be LTS (long-term support)?
 127
 128 A: All official releases have been through a comprehensive testing
 129    process and are suitable for production use.  Planned releases will
 130    occur several times a year.  If a significant bug is identified in an
 131    LTS release, we will provide an updated release that includes the
 132    fix.  Releases that are not LTS may not be fixed and may just be
 133    supplanted by the next major release.  The current LTS release is
 134    2.3.x.
 135
 136 ### Q: What Linux kernel versions does each Open vSwitch release work with?
 137
 138 A: The following table lists the Linux kernel versions against which the
 139    given versions of the Open vSwitch kernel module will successfully
 140    build.  The Linux kernel versions are upstream kernel versions, so
 141    Linux kernels modified from the upstream sources may not build in
 142    some cases even if they are based on a supported version.  This is
 143    most notably true of Red Hat Enterprise Linux (RHEL) kernels, which
 144    are extensively modified from upstream.
 145
 146 | Open vSwitch | Linux kernel
 147 |:------------:|:-------------:
 148 |    1.4.x     | 2.6.18 to 3.2
 149 |    1.5.x     | 2.6.18 to 3.2
 150 |    1.6.x     | 2.6.18 to 3.2
 151 |    1.7.x     | 2.6.18 to 3.3
 152 |    1.8.x     | 2.6.18 to 3.4
 153 |    1.9.x     | 2.6.18 to 3.8
 154 |    1.10.x    | 2.6.18 to 3.8
 155 |    1.11.x    | 2.6.18 to 3.8
 156 |    2.0.x     | 2.6.32 to 3.10
 157 |    2.1.x     | 2.6.32 to 3.11
 158 |    2.3.x     | 2.6.32 to 3.14
 159 |    2.4.x     | 2.6.32 to 3.19
 160
 161    Open vSwitch userspace should also work with the Linux kernel module
 162    built into Linux 3.3 and later.
 163
 164    Open vSwitch userspace is not sensitive to the Linux kernel version.
 165    It should build against almost any kernel, certainly against 2.6.32
 166    and later.
 167
 168 ### Q: I get an error like this when I configure Open vSwitch:
 169
 170        configure: error: Linux kernel in <dir> is version <x>, but
 171        version newer than <y> is not supported (please refer to the
 172        FAQ for advice)
 173
 174    What should I do?
 175
 176 A: You have the following options:
 177
 178    - Use the Linux kernel module supplied with the kernel that you are
 179      using.  (See also the following FAQ.)
 180
 181    - If there is a newer released version of Open vSwitch, consider
 182      building that one, because it may support the kernel that you are
 183      building against.  (To find out, consult the table in the
 184      previous FAQ.)
 185
 186    - The Open vSwitch "master" branch may support the kernel that you
 187      are using, so consider building the kernel module from "master".
 188
 189   All versions of Open vSwitch userspace are compatible with all
 190   versions of the Open vSwitch kernel module, so you do not have to
 191   use the kernel module from one source along with the userspace
 192   programs from the same source.
 193
 194 ### Q: What features are not available in the Open vSwitch kernel datapath that ships as part of the upstream Linux kernel?
 195
 196 A: The kernel module in upstream Linux does not include support for
 197    LISP. Work is in progress to add support for LISP to the upstream
 198    Linux version of the Open vSwitch kernel module. For now, if you
 199    need this feature, use the kernel module from the Open vSwitch
 200    distribution instead of the upstream Linux kernel module.
 201
 202    Certain features require kernel support to function or to have
 203    reasonable performance. If the ovs-vswitchd log file indicates that
 204    a feature is not supported, consider upgrading to a newer upstream
 205    Linux release or using the kernel module paired with the userspace
 206    distribution.
 207
 208 ### Q: Why do tunnels not work when using a kernel module other than the one packaged with Open vSwitch?
 209
 210 A: Support for tunnels was added to the upstream Linux kernel module
 211    after the rest of Open vSwitch. As a result, some kernels may contain
 212    support for Open vSwitch but not tunnels. The minimum kernel version
 213    that supports each tunnel protocol is:
 214
 215 | Protocol |  Linux Kernel
 216 |:--------:|:-------------:
 217 | GRE      |    3.11
 218 | VXLAN    |    3.12
 219 | Geneve   |    3.18
 220 | LISP     | <not upstream>
 221 | STT      | <not upstream>
 222
 223    If you are using a version of the kernel that is older than the one
 224    listed above, it is still possible to use that tunnel protocol. However,
 225    you must compile and install the kernel module included with the Open
 226    vSwitch distribution rather than the one on your machine. If problems
 227    persist after doing this, check to make sure that the module that is
 228    loaded is the one you expect.
 229
 230 ### Q: Why are UDP tunnel checksums not computed for VXLAN or Geneve?
 231
 232 A: Generating outer UDP checksums requires kernel support that was not
 233    part of the initial implementation of these protocols. If using the
 234    upstream Linux Open vSwitch module, you must use kernel 4.0 or
 235    newer. The out-of-tree modules from Open vSwitch release 2.4 and later
 236    support UDP checksums.
 237
 238 ### Q: What features are not available when using the userspace datapath?
 239
 240 A: Tunnel virtual ports are not supported, as described in the
 241    previous answer.  It is also not possible to use queue-related
 242    actions.  On Linux kernels before 2.6.39, maximum-sized VLAN packets
 243    may not be transmitted.
 244
 245 ### Q: What Linux kernel versions does IPFIX flow monitoring work with?
 246
 247 A: IPFIX flow monitoring requires the Linux kernel module from Linux
 248    3.10 or later, or the out-of-tree module from Open vSwitch version
 249    1.10.90 or later.
 250
 251 ### Q: Should userspace or kernel be upgraded first to minimize downtime?
 252
 253    In general, the Open vSwitch userspace should be used with the
 254    kernel version included in the same release or with the version
 255    from upstream Linux.  However, when upgrading between two releases
 256    of Open vSwitch it is best to migrate userspace first to reduce
 257    the possibility of incompatibilities.
 258
 259 ### Q: What happened to the bridge compatibility feature?
 260
 261 A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier.
 262    When it was enabled, Open vSwitch imitated the interface of the
 263    Linux kernel "bridge" module.  This allowed users to drop Open
 264    vSwitch into environments designed to use the Linux kernel bridge
 265    module without adapting the environment to use Open vSwitch.
 266
 267    Open vSwitch 1.10 and later do not support bridge compatibility.
 268    The feature was dropped because version 1.10 adopted a new internal
 269    architecture that made bridge compatibility difficult to maintain.
 270    Now that many environments use OVS directly, it would be rarely
 271    useful in any case.
 272
 273    To use bridge compatibility, install OVS 1.9 or earlier, including
 274    the accompanying kernel modules (both the main and bridge
 275    compatibility modules), following the instructions that come with
 276    the release.  Be sure to start the ovs-brcompatd daemon.
 277
 278
 279 Terminology
 280 -----------
 281
 282 ### Q: I thought Open vSwitch was a virtual Ethernet switch, but the documentation keeps talking about bridges.  What's a bridge?
 283
 284 A: In networking, the terms "bridge" and "switch" are synonyms.  Open
 285    vSwitch implements an Ethernet switch, which means that it is also
 286    an Ethernet bridge.
 287
 288 ### Q: What's a VLAN?
 289
 290 A: See the "VLAN" section below.
 291
 292
 293 Basic Configuration
 294 -------------------
 295
 296 ### Q: How do I configure a port as an access port?
 297
 298 A: Add "tag=VLAN" to your "ovs-vsctl add-port" command.  For example,
 299    the following commands configure br0 with eth0 as a trunk port (the
 300    default) and tap0 as an access port for VLAN 9:
 301
 302        ovs-vsctl add-br br0
 303        ovs-vsctl add-port br0 eth0
 304        ovs-vsctl add-port br0 tap0 tag=9
 305
 306    If you want to configure an already added port as an access port,
 307    use "ovs-vsctl set", e.g.:
 308
 309        ovs-vsctl set port tap0 tag=9
 310
 311 ### Q: How do I configure a port as a SPAN port, that is, enable mirroring of all traffic to that port?
 312
 313 A: The following commands configure br0 with eth0 and tap0 as trunk
 314    ports.  All traffic coming in or going out on eth0 or tap0 is also
 315    mirrored to tap1; any traffic arriving on tap1 is dropped:
 316
 317        ovs-vsctl add-br br0
 318        ovs-vsctl add-port br0 eth0
 319        ovs-vsctl add-port br0 tap0
 320        ovs-vsctl add-port br0 tap1 \
 321            -- --id=@p get port tap1 \
 322            -- --id=@m create mirror name=m0 select-all=true output-port=@p \
 323            -- set bridge br0 mirrors=@m
 324
 325    To later disable mirroring, run:
 326
 327        ovs-vsctl clear bridge br0 mirrors
 328
 329 ### Q: Does Open vSwitch support configuring a port in promiscuous mode?
 330
 331 A: Yes.  How you configure it depends on what you mean by "promiscuous
 332    mode":
 333
 334   - Conventionally, "promiscuous mode" is a feature of a network
 335     interface card.  Ordinarily, a NIC passes to the CPU only the
 336     packets actually destined to its host machine.  It discards
 337     the rest to avoid wasting memory and CPU cycles.  When
 338     promiscuous mode is enabled, however, it passes every packet
 339     to the CPU.  On an old-style shared-media or hub-based
 340     network, this allows the host to spy on all packets on the
 341     network.  But in the switched networks that are almost
 342     everywhere these days, promiscuous mode doesn't have much
 343     effect, because few packets not destined to a host are
 344     delivered to the host's NIC.
 345
 346     This form of promiscuous mode is configured in the guest OS of
 347     the VMs on your bridge, e.g. with "ifconfig".
 348
 349   - The VMware vSwitch uses a different definition of "promiscuous
 350     mode".  When you configure promiscuous mode on a VMware vNIC,
 351     the vSwitch sends a copy of every packet received by the
 352     vSwitch to that vNIC.  That has a much bigger effect than just
 353     enabling promiscuous mode in a guest OS.  Rather than getting
 354     a few stray packets for which the switch does not yet know the
 355     correct destination, the vNIC gets every packet.  The effect
 356     is similar to replacing the vSwitch by a virtual hub.
 357
 358     This "promiscuous mode" is what switches normally call "port
 359     mirroring" or "SPAN".  For information on how to configure
 360     SPAN, see "How do I configure a port as a SPAN port, that is,
 361     enable mirroring of all traffic to that port?"
 362
 363 ### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN?
 364
 365 A: The following commands configure br0 with eth0 as a trunk port and
 366    tap0 as an access port for VLAN 10.  All traffic coming in or going
 367    out on tap0, as well as traffic coming in or going out on eth0 in
 368    VLAN 10, is also mirrored to VLAN 15 on eth0.  The original tag for
 369    VLAN 10, in cases where one is present, is dropped as part of
 370    mirroring:
 371
 372        ovs-vsctl add-br br0
 373        ovs-vsctl add-port br0 eth0
 374        ovs-vsctl add-port br0 tap0 tag=10
 375        ovs-vsctl \
 376            -- --id=@m create mirror name=m0 select-all=true select-vlan=10 \
 377                                     output-vlan=15 \
 378            -- set bridge br0 mirrors=@m
 379
 380    To later disable mirroring, run:
 381
 382        ovs-vsctl clear bridge br0 mirrors
 383
 384    Mirroring to a VLAN can disrupt a network that contains unmanaged
 385    switches.  See ovs-vswitchd.conf.db(5) for details.  Mirroring to a
 386    GRE tunnel has fewer caveats than mirroring to a VLAN and should
 387    generally be preferred.
 388
 389 ### Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
 390
 391 A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor
 392    of the specified output-vlan.  This loss of information may make
 393    the mirrored traffic too hard to interpret.
 394
 395    To mirror multiple VLANs, use the commands above, but specify a
 396    comma-separated list of VLANs as the value for select-vlan.  To
 397    mirror every VLAN, use the commands above, but omit select-vlan and
 398    its value entirely.
 399
 400    When a packet arrives on a VLAN that is used as a mirror output
 401    VLAN, the mirror is disregarded.  Instead, in standalone mode, OVS
 402    floods the packet across all the ports for which the mirror output
 403    VLAN is configured.  (If an OpenFlow controller is in use, then it
 404    can override this behavior through the flow table.)  If OVS is used
 405    as an intermediate switch, rather than an edge switch, this ensures
 406    that the RSPAN traffic is distributed through the network.
 407
 408    Mirroring to a VLAN can disrupt a network that contains unmanaged
 409    switches.  See ovs-vswitchd.conf.db(5) for details.  Mirroring to a
 410    GRE tunnel has fewer caveats than mirroring to a VLAN and should
 411    generally be preferred.
 412
 413 ### Q: How do I configure mirroring of all traffic to a GRE tunnel?
 414
 415 A: The following commands configure br0 with eth0 and tap0 as trunk
 416    ports.  All traffic coming in or going out on eth0 or tap0 is also
 417    mirrored to gre0, a GRE tunnel to the remote host 192.168.1.10; any
 418    traffic arriving on gre0 is dropped:
 419
 420        ovs-vsctl add-br br0
 421        ovs-vsctl add-port br0 eth0
 422        ovs-vsctl add-port br0 tap0
 423        ovs-vsctl add-port br0 gre0 \
 424            -- set interface gre0 type=gre options:remote_ip=192.168.1.10 \
 425            -- --id=@p get port gre0 \
 426            -- --id=@m create mirror name=m0 select-all=true output-port=@p \
 427            -- set bridge br0 mirrors=@m
 428
 429    To later disable mirroring and destroy the GRE tunnel:
 430
 431        ovs-vsctl clear bridge br0 mirrors
 432        ovs-vcstl del-port br0 gre0
 433
 434 ### Q: Does Open vSwitch support ERSPAN?
 435
 436 A: No.  ERSPAN is an undocumented proprietary protocol.  As an
 437    alternative, Open vSwitch supports mirroring to a GRE tunnel (see
 438    above).
 439
 440 ### Q: How do I connect two bridges?
 441
 442 A: First, why do you want to do this?  Two connected bridges are not
 443    much different from a single bridge, so you might as well just have
 444    a single bridge with all your ports on it.
 445
 446    If you still want to connect two bridges, you can use a pair of
 447    patch ports.  The following example creates bridges br0 and br1,
 448    adds eth0 and tap0 to br0, adds tap1 to br1, and then connects br0
 449    and br1 with a pair of patch ports.
 450
 451        ovs-vsctl add-br br0
 452        ovs-vsctl add-port br0 eth0
 453        ovs-vsctl add-port br0 tap0
 454        ovs-vsctl add-br br1
 455        ovs-vsctl add-port br1 tap1
 456        ovs-vsctl \
 457            -- add-port br0 patch0 \
 458            -- set interface patch0 type=patch options:peer=patch1 \
 459            -- add-port br1 patch1 \
 460            -- set interface patch1 type=patch options:peer=patch0
 461
 462    Bridges connected with patch ports are much like a single bridge.
 463    For instance, if the example above also added eth1 to br1, and both
 464    eth0 and eth1 happened to be connected to the same next-hop switch,
 465    then you could loop your network just as you would if you added
 466    eth0 and eth1 to the same bridge (see the "Configuration Problems"
 467    section below for more information).
 468
 469    If you are using Open vSwitch 1.9 or an earlier version, then you
 470    need to be using the kernel module bundled with Open vSwitch rather
 471    than the one that is integrated into Linux 3.3 and later, because
 472    Open vSwitch 1.9 and earlier versions need kernel support for patch
 473    ports.  This also means that in Open vSwitch 1.9 and earlier, patch
 474    ports will not work with the userspace datapath, only with the
 475    kernel module.
 476
 477 ### Q: How do I configure a bridge without an OpenFlow local port?  (Local port in the sense of OFPP_LOCAL)
 478
 479 A: Open vSwitch does not support such a configuration.
 480    Bridges always have their local ports.
 481
 482
 483 Implementation Details
 484 ----------------------
 485
 486 ### Q: I hear OVS has a couple of kinds of flows.  Can you tell me about them?
 487
 488 A: Open vSwitch uses different kinds of flows for different purposes:
 489
 490   - OpenFlow flows are the most important kind of flow.  OpenFlow
 491     controllers use these flows to define a switch's policy.
 492     OpenFlow flows support wildcards, priorities, and multiple
 493     tables.
 494
 495     When in-band control is in use, Open vSwitch sets up a few
 496     "hidden" flows, with priority higher than a controller or the
 497     user can configure, that are not visible via OpenFlow.  (See
 498     the "Controller" section of the FAQ for more information
 499     about hidden flows.)
 500
 501   - The Open vSwitch software switch implementation uses a second
 502     kind of flow internally.  These flows, called "datapath" or
 503     "kernel" flows, do not support priorities and comprise only a
 504     single table, which makes them suitable for caching.  (Like
 505     OpenFlow flows, datapath flows do support wildcarding, in Open
 506     vSwitch 1.11 and later.)  OpenFlow flows and datapath flows
 507     also support different actions and number ports differently.
 508
 509     Datapath flows are an implementation detail that is subject to
 510     change in future versions of Open vSwitch.  Even with the
 511     current version of Open vSwitch, hardware switch
 512     implementations do not necessarily use this architecture.
 513
 514    Users and controllers directly control only the OpenFlow flow
 515    table.  Open vSwitch manages the datapath flow table itself, so
 516    users should not normally be concerned with it.
 517
 518 ### Q: Why are there so many different ways to dump flows?
 519
 520 A: Open vSwitch has two kinds of flows (see the previous question), so
 521    it has commands with different purposes for dumping each kind of
 522    flow:
 523
 524   - `ovs-ofctl dump-flows <br>` dumps OpenFlow flows, excluding
 525     hidden flows.  This is the most commonly useful form of flow
 526     dump.  (Unlike the other commands, this should work with any
 527     OpenFlow switch, not just Open vSwitch.)
 528
 529   - `ovs-appctl bridge/dump-flows <br>` dumps OpenFlow flows,
 530     including hidden flows.  This is occasionally useful for
 531     troubleshooting suspected issues with in-band control.
 532
 533   - `ovs-dpctl dump-flows [dp]` dumps the datapath flow table
 534     entries for a Linux kernel-based datapath.  In Open vSwitch
 535     1.10 and later, ovs-vswitchd merges multiple switches into a
 536     single datapath, so it will show all the flows on all your
 537     kernel-based switches.  This command can occasionally be
 538     useful for debugging.
 539
 540   - `ovs-appctl dpif/dump-flows <br>`, new in Open vSwitch 1.10,
 541     dumps datapath flows for only the specified bridge, regardless
 542     of the type.
 543
 544 ### Q: How does multicast snooping works with VLANs?
 545
 546 A: Open vSwitch maintains snooping tables for each VLAN.
 547
 548
 549 Performance
 550 -----------
 551
 552 ### Q: I just upgraded and I see a performance drop.  Why?
 553
 554 A: The OVS kernel datapath may have been updated to a newer version than
 555    the OVS userspace components.  Sometimes new versions of OVS kernel
 556    module add functionality that is backwards compatible with older
 557    userspace components but may cause a drop in performance with them.
 558    Especially, if a kernel module from OVS 2.1 or newer is paired with
 559    OVS userspace 1.10 or older, there will be a performance drop for
 560    TCP traffic.
 561
 562    Updating the OVS userspace components to the latest released
 563    version should fix the performance degradation.
 564
 565    To get the best possible performance and functionality, it is
 566    recommended to pair the same versions of the kernel module and OVS
 567    userspace.
 568
 569
 570 Configuration Problems
 571 ----------------------
 572
 573 ### Q: I created a bridge and added my Ethernet port to it, using commands
 574    like these:
 575
 576        ovs-vsctl add-br br0
 577        ovs-vsctl add-port br0 eth0
 578
 579    and as soon as I ran the "add-port" command I lost all connectivity
 580    through eth0.  Help!
 581
 582 A: A physical Ethernet device that is part of an Open vSwitch bridge
 583    should not have an IP address.  If one does, then that IP address
 584    will not be fully functional.
 585
 586    You can restore functionality by moving the IP address to an Open
 587    vSwitch "internal" device, such as the network device named after
 588    the bridge itself.  For example, assuming that eth0's IP address is
 589    192.168.128.5, you could run the commands below to fix up the
 590    situation:
 591
 592        ifconfig eth0 0.0.0.0
 593        ifconfig br0 192.168.128.5
 594
 595    (If your only connection to the machine running OVS is through the
 596    IP address in question, then you would want to run all of these
 597    commands on a single command line, or put them into a script.)  If
 598    there were any additional routes assigned to eth0, then you would
 599    also want to use commands to adjust these routes to go through br0.
 600
 601    If you use DHCP to obtain an IP address, then you should kill the
 602    DHCP client that was listening on the physical Ethernet interface
 603    (e.g. eth0) and start one listening on the internal interface
 604    (e.g. br0).  You might still need to manually clear the IP address
 605    from the physical interface (e.g. with "ifconfig eth0 0.0.0.0").
 606
 607    There is no compelling reason why Open vSwitch must work this way.
 608    However, this is the way that the Linux kernel bridge module has
 609    always worked, so it's a model that those accustomed to Linux
 610    bridging are already used to.  Also, the model that most people
 611    expect is not implementable without kernel changes on all the
 612    versions of Linux that Open vSwitch supports.
 613
 614    By the way, this issue is not specific to physical Ethernet
 615    devices.  It applies to all network devices except Open vSwitch
 616    "internal" devices.
 617
 618 ### Q: I created a bridge and added a couple of Ethernet ports to it,
 619 ### using commands like these:
 620
 621        ovs-vsctl add-br br0
 622        ovs-vsctl add-port br0 eth0
 623        ovs-vsctl add-port br0 eth1
 624
 625    and now my network seems to have melted: connectivity is unreliable
 626    (even connectivity that doesn't go through Open vSwitch), all the
 627    LEDs on my physical switches are blinking, wireshark shows
 628    duplicated packets, and CPU usage is very high.
 629
 630 A: More than likely, you've looped your network.  Probably, eth0 and
 631    eth1 are connected to the same physical Ethernet switch.  This
 632    yields a scenario where OVS receives a broadcast packet on eth0 and
 633    sends it out on eth1, then the physical switch connected to eth1
 634    sends the packet back on eth0, and so on forever.  More complicated
 635    scenarios, involving a loop through multiple switches, are possible
 636    too.
 637
 638    The solution depends on what you are trying to do:
 639
 640    - If you added eth0 and eth1 to get higher bandwidth or higher
 641      reliability between OVS and your physical Ethernet switch,
 642      use a bond.  The following commands create br0 and then add
 643      eth0 and eth1 as a bond:
 644
 645          ovs-vsctl add-br br0
 646          ovs-vsctl add-bond br0 bond0 eth0 eth1
 647
 648      Bonds have tons of configuration options.  Please read the
 649      documentation on the Port table in ovs-vswitchd.conf.db(5)
 650      for all the details.
 651
 652    - Perhaps you don't actually need eth0 and eth1 to be on the
 653      same bridge.  For example, if you simply want to be able to
 654      connect each of them to virtual machines, then you can put
 655      each of them on a bridge of its own:
 656
 657          ovs-vsctl add-br br0
 658          ovs-vsctl add-port br0 eth0
 659
 660          ovs-vsctl add-br br1
 661          ovs-vsctl add-port br1 eth1
 662
 663      and then connect VMs to br0 and br1.  (A potential
 664      disadvantage is that traffic cannot directly pass between br0
 665      and br1.  Instead, it will go out eth0 and come back in eth1,
 666      or vice versa.)
 667
 668    - If you have a redundant or complex network topology and you
 669      want to prevent loops, turn on spanning tree protocol (STP).
 670      The following commands create br0, enable STP, and add eth0
 671      and eth1 to the bridge.  The order is important because you
 672      don't want have to have a loop in your network even
 673      transiently:
 674
 675          ovs-vsctl add-br br0
 676          ovs-vsctl set bridge br0 stp_enable=true
 677          ovs-vsctl add-port br0 eth0
 678          ovs-vsctl add-port br0 eth1
 679
 680      The Open vSwitch implementation of STP is not well tested.
 681      Please report any bugs you observe, but if you'd rather avoid
 682      acting as a beta tester then another option might be your
 683      best shot.
 684
 685 ### Q: I can't seem to use Open vSwitch in a wireless network.
 686
 687 A: Wireless base stations generally only allow packets with the source
 688    MAC address of NIC that completed the initial handshake.
 689    Therefore, without MAC rewriting, only a single device can
 690    communicate over a single wireless link.
 691
 692    This isn't specific to Open vSwitch, it's enforced by the access
 693    point, so the same problems will show up with the Linux bridge or
 694    any other way to do bridging.
 695
 696 ### Q: I can't seem to add my PPP interface to an Open vSwitch bridge.
 697
 698 A: PPP most commonly carries IP packets, but Open vSwitch works only
 699    with Ethernet frames.  The correct way to interface PPP to an
 700    Ethernet network is usually to use routing instead of switching.
 701
 702 ### Q: Is there any documentation on the database tables and fields?
 703
 704 A: Yes.  ovs-vswitchd.conf.db(5) is a comprehensive reference.
 705
 706 ### Q: When I run ovs-dpctl I no longer see the bridges I created.  Instead,
 707    I only see a datapath called "ovs-system".  How can I see datapath
 708    information about a particular bridge?
 709
 710 A: In version 1.9.0, OVS switched to using a single datapath that is
 711    shared by all bridges of that type.  The "ovs-appctl dpif/*"
 712    commands provide similar functionality that is scoped by the bridge.
 713
 714 ### Q: I created a GRE port using ovs-vsctl so why can't I send traffic or
 715    see the port in the datapath?
 716
 717 A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module
 718    cannot be loaded at the same time. It is likely that on your system the
 719    Linux GRE module is already loaded and blocking OVS (to confirm, check
 720    dmesg for errors regarding GRE registration). To fix this, unload all
 721    GRE modules that appear in lsmod as well as the OVS kernel module. You
 722    can then reload the OVS module following the directions in
 723    [INSTALL.md], which will ensure that dependencies are satisfied.
 724
 725 ### Q: Open vSwitch does not seem to obey my packet filter rules.
 726
 727 A: It depends on mechanisms and configurations you want to use.
 728
 729    You cannot usefully use typical packet filters, like iptables, on
 730    physical Ethernet ports that you add to an Open vSwitch bridge.
 731    This is because Open vSwitch captures packets from the interface at
 732    a layer lower below where typical packet-filter implementations
 733    install their hooks.  (This actually applies to any interface of
 734    type "system" that you might add to an Open vSwitch bridge.)
 735
 736    You can usefully use typical packet filters on Open vSwitch
 737    internal ports as they are mostly ordinary interfaces from the point
 738    of view of packet filters.
 739
 740    For example, suppose you create a bridge br0 and add Ethernet port
 741    eth0 to it.  Then you can usefully add iptables rules to affect the
 742    internal interface br0, but not the physical interface eth0.  (br0
 743    is also where you would add an IP address, as discussed elsewhere
 744    in the FAQ.)
 745
 746    For simple filtering rules, it might be possible to achieve similar
 747    results by installing appropriate OpenFlow flows instead.
 748
 749    If the use of a particular packet filter setup is essential, Open
 750    vSwitch might not be the best choice for you.  On Linux, you might
 751    want to consider using the Linux Bridge.  (This is the only choice if
 752    you want to use ebtables rules.)  On NetBSD, you might want to
 753    consider using the bridge(4) with BRIDGE_IPF option.
 754
 755 ### Q: It seems that Open vSwitch does nothing when I removed a port and
 756    then immediately put it back.  For example, consider that p1 is
 757    a port of type=internal:
 758
 759        ovs-vsctl del-port br0 p1 -- \
 760            add-port br0 p1 -- \
 761            set interface p1 type=internal
 762
 763 A: It's an expected behaviour.
 764
 765    If del-port and add-port happen in a single OVSDB transaction as
 766    your example, Open vSwitch always "skips" the intermediate steps.
 767    Even if they are done in multiple transactions, it's still allowed
 768    for Open vSwitch to skip the intermediate steps and just implement
 769    the overall effect.  In both cases, your example would be turned
 770    into a no-op.
 771
 772    If you want to make Open vSwitch actually destroy and then re-create
 773    the port for some side effects like resetting kernel setting for the
 774    corresponding interface, you need to separate operations into multiple
 775    OVSDB transactions and ensure that at least the first one does not have
 776    --no-wait.  In the following example, the first ovs-vsctl will block
 777    until Open vSwitch reloads the new configuration and removes the port:
 778
 779        ovs-vsctl del-port br0 p1
 780        ovs-vsctl add-port br0 p1 -- \
 781            set interface p1 type=internal
 782
 783 ### Q: I want to add thousands of ports to an Open vSwitch bridge, but
 784    it takes too long (minutes or hours) to do it with ovs-vsctl.  How
 785    can I do it faster?
 786
 787 A: If you add them one at a time with ovs-vsctl, it can take a long
 788    time to add thousands of ports to an Open vSwitch bridge.  This is
 789    because every invocation of ovs-vsctl first reads the current
 790    configuration from OVSDB.  As the number of ports grows, this
 791    starts to take an appreciable amount of time, and when it is
 792    repeated thousands of times the total time becomes significant.
 793
 794    The solution is to add the ports in one invocation of ovs-vsctl (or
 795    a small number of them).  For example, using bash:
 796
 797        ovs-vsctl add-br br0
 798        cmds=; for i in {1..5000}; do cmds+=" -- add-port br0 p$i"; done
 799        ovs-vsctl $cmds
 800
 801    takes seconds, not minutes or hours, in the OVS sandbox environment.
 802
 803 ### Q: I created a bridge named br0.  My bridge shows up in "ovs-vsctl
 804     show", but "ovs-ofctl show br0" just prints "br0 is not a bridge
 805     or a socket".
 806
 807 A: Open vSwitch wasn't able to create the bridge.  Check the
 808    ovs-vswitchd log for details (Debian and Red Hat packaging for Open
 809    vSwitch put it in /var/log/openvswitch/ovs-vswitchd.log).
 810
 811    In general, the Open vSwitch database reflects the desired
 812    configuration state.  ovs-vswitchd monitors the database and, when
 813    it changes, reconfigures the system to reflect the new desired
 814    state.  This normally happens very quickly.  Thus, a discrepancy
 815    between the database and the actual state indicates that
 816    ovs-vswitchd could not implement the configuration, and so one
 817    should check the log to find out why.  (Another possible cause is
 818    that ovs-vswitchd is not running.  This will make "ovs-vsctl"
 819    commands hang, if they change the configuration, unless one
 820    specifies "--no-wait".)
 821
 822 ### Q: I have a bridge br0.  I added a new port vif1.0, and it shows
 823     up in "ovs-vsctl show", but "ovs-vsctl list port" says that it has
 824     OpenFlow port ("ofport") -1, and "ovs-ofctl show br0" doesn't show
 825     vif1.0 at all.
 826
 827 A: Open vSwitch wasn't able to create the port.  Check the
 828    ovs-vswitchd log for details (Debian and Red Hat packaging for Open
 829    vSwitch put it in /var/log/openvswitch/ovs-vswitchd.log).  Please
 830    see the previous question for more information.
 831
 832    You may want to upgrade to Open vSwitch 2.3 (or later), in which
 833    ovs-vsctl will immediately report when there is an issue creating a
 834    port.
 835
 836
 837 Quality of Service (QoS)
 838 ------------------------
 839
 840 ### Q: How do I configure Quality of Service (QoS)?
 841
 842 A: Suppose that you want to set up bridge br0 connected to physical
 843    Ethernet port eth0 (a 1 Gbps device) and virtual machine interfaces
 844    vif1.0 and vif2.0, and that you want to limit traffic from vif1.0
 845    to eth0 to 10 Mbps and from vif2.0 to eth0 to 20 Mbps.  Then, you
 846    could configure the bridge this way:
 847
 848        ovs-vsctl -- \
 849            add-br br0 -- \
 850            add-port br0 eth0 -- \
 851            add-port br0 vif1.0 -- set interface vif1.0 ofport_request=5 -- \
 852            add-port br0 vif2.0 -- set interface vif2.0 ofport_request=6 -- \
 853            set port eth0 qos=@newqos -- \
 854            --id=@newqos create qos type=linux-htb \
 855                other-config:max-rate=1000000000 \
 856                queues:123=@vif10queue \
 857                queues:234=@vif20queue -- \
 858            --id=@vif10queue create queue other-config:max-rate=10000000 -- \
 859            --id=@vif20queue create queue other-config:max-rate=20000000
 860
 861    At this point, bridge br0 is configured with the ports and eth0 is
 862    configured with the queues that you need for QoS, but nothing is
 863    actually directing packets from vif1.0 or vif2.0 to the queues that
 864    we have set up for them.  That means that all of the packets to
 865    eth0 are going to the "default queue", which is not what we want.
 866
 867    We use OpenFlow to direct packets from vif1.0 and vif2.0 to the
 868    queues reserved for them:
 869
 870        ovs-ofctl add-flow br0 in_port=5,actions=set_queue:123,normal
 871        ovs-ofctl add-flow br0 in_port=6,actions=set_queue:234,normal
 872
 873    Each of the above flows matches on the input port, sets up the
 874    appropriate queue (123 for vif1.0, 234 for vif2.0), and then
 875    executes the "normal" action, which performs the same switching
 876    that Open vSwitch would have done without any OpenFlow flows being
 877    present.  (We know that vif1.0 and vif2.0 have OpenFlow port
 878    numbers 5 and 6, respectively, because we set their ofport_request
 879    columns above.  If we had not done that, then we would have needed
 880    to find out their port numbers before setting up these flows.)
 881
 882    Now traffic going from vif1.0 or vif2.0 to eth0 should be
 883    rate-limited.
 884
 885    By the way, if you delete the bridge created by the above commands,
 886    with:
 887
 888        ovs-vsctl del-br br0
 889
 890    then that will leave one unreferenced QoS record and two
 891    unreferenced Queue records in the Open vSwich database.  One way to
 892    clear them out, assuming you don't have other QoS or Queue records
 893    that you want to keep, is:
 894
 895        ovs-vsctl -- --all destroy QoS -- --all destroy Queue
 896
 897    If you do want to keep some QoS or Queue records, or the Open
 898    vSwitch you are using is older than version 1.8 (which added the
 899    --all option), then you will have to destroy QoS and Queue records
 900    individually.
 901
 902 ### Q: I configured Quality of Service (QoS) in my OpenFlow network by
 903    adding records to the QoS and Queue table, but the results aren't
 904    what I expect.
 905
 906 A: Did you install OpenFlow flows that use your queues?  This is the
 907    primary way to tell Open vSwitch which queues you want to use.  If
 908    you don't do this, then the default queue will be used, which will
 909    probably not have the effect you want.
 910
 911    Refer to the previous question for an example.
 912
 913 ### Q: I'd like to take advantage of some QoS feature that Open vSwitch
 914    doesn't yet support.  How do I do that?
 915
 916 A: Open vSwitch does not implement QoS itself.  Instead, it can
 917    configure some, but not all, of the QoS features built into the
 918    Linux kernel.  If you need some QoS feature that OVS cannot
 919    configure itself, then the first step is to figure out whether
 920    Linux QoS supports that feature.  If it does, then you can submit a
 921    patch to support Open vSwitch configuration for that feature, or
 922    you can use "tc" directly to configure the feature in Linux.  (If
 923    Linux QoS doesn't support the feature you want, then first you have
 924    to add that support to Linux.)
 925
 926 ### Q: I configured QoS, correctly, but my measurements show that it isn't
 927    working as well as I expect.
 928
 929 A: With the Linux kernel, the Open vSwitch implementation of QoS has
 930    two aspects:
 931
 932    - Open vSwitch configures a subset of Linux kernel QoS
 933      features, according to what is in OVSDB.  It is possible that
 934      this code has bugs.  If you believe that this is so, then you
 935      can configure the Linux traffic control (QoS) stack directly
 936      with the "tc" program.  If you get better results that way,
 937      you can send a detailed bug report to bugs@openvswitch.org.
 938
 939      It is certain that Open vSwitch cannot configure every Linux
 940      kernel QoS feature.  If you need some feature that OVS cannot
 941      configure, then you can also use "tc" directly (or add that
 942      feature to OVS).
 943
 944    - The Open vSwitch implementation of OpenFlow allows flows to
 945      be directed to particular queues.  This is pretty simple and
 946      unlikely to have serious bugs at this point.
 947
 948    However, most problems with QoS on Linux are not bugs in Open
 949    vSwitch at all.  They tend to be either configuration errors
 950    (please see the earlier questions in this section) or issues with
 951    the traffic control (QoS) stack in Linux.  The Open vSwitch
 952    developers are not experts on Linux traffic control.  We suggest
 953    that, if you believe you are encountering a problem with Linux
 954    traffic control, that you consult the tc manpages (e.g. tc(8),
 955    tc-htb(8), tc-hfsc(8)), web resources (e.g. http://lartc.org/), or
 956    mailing lists (e.g. http://vger.kernel.org/vger-lists.html#netdev).
 957
 958 ### Q: Does Open vSwitch support OpenFlow meters?
 959
 960 A: Since version 2.0, Open vSwitch has OpenFlow protocol support for
 961    OpenFlow meters.  There is no implementation of meters in the Open
 962    vSwitch software switch (neither the kernel-based nor userspace
 963    switches).
 964
 965
 966 VLANs
 967 -----
 968
 969 ### Q: What's a VLAN?
 970
 971 A: At the simplest level, a VLAN (short for "virtual LAN") is a way to
 972    partition a single switch into multiple switches.  Suppose, for
 973    example, that you have two groups of machines, group A and group B.
 974    You want the machines in group A to be able to talk to each other,
 975    and you want the machine in group B to be able to talk to each
 976    other, but you don't want the machines in group A to be able to
 977    talk to the machines in group B.  You can do this with two
 978    switches, by plugging the machines in group A into one switch and
 979    the machines in group B into the other switch.
 980
 981    If you only have one switch, then you can use VLANs to do the same
 982    thing, by configuring the ports for machines in group A as VLAN
 983    "access ports" for one VLAN and the ports for group B as "access
 984    ports" for a different VLAN.  The switch will only forward packets
 985    between ports that are assigned to the same VLAN, so this
 986    effectively subdivides your single switch into two independent
 987    switches, one for each group of machines.
 988
 989    So far we haven't said anything about VLAN headers.  With access
 990    ports, like we've described so far, no VLAN header is present in
 991    the Ethernet frame.  This means that the machines (or switches)
 992    connected to access ports need not be aware that VLANs are
 993    involved, just like in the case where we use two different physical
 994    switches.
 995
 996    Now suppose that you have a whole bunch of switches in your
 997    network, instead of just one, and that some machines in group A are
 998    connected directly to both switches 1 and 2.  To allow these
 999    machines to talk to each other, you could add an access port for
1000    group A's VLAN to switch 1 and another to switch 2, and then
1001    connect an Ethernet cable between those ports.  That works fine,
1002    but it doesn't scale well as the number of switches and the number
1003    of VLANs increases, because you use up a lot of valuable switch
1004    ports just connecting together your VLANs.
1005
1006    This is where VLAN headers come in.  Instead of using one cable and
1007    two ports per VLAN to connect a pair of switches, we configure a
1008    port on each switch as a VLAN "trunk port".  Packets sent and
1009    received on a trunk port carry a VLAN header that says what VLAN
1010    the packet belongs to, so that only two ports total are required to
1011    connect the switches, regardless of the number of VLANs in use.
1012    Normally, only switches (either physical or virtual) are connected
1013    to a trunk port, not individual hosts, because individual hosts
1014    don't expect to see a VLAN header in the traffic that they receive.
1015
1016    None of the above discussion says anything about particular VLAN
1017    numbers.  This is because VLAN numbers are completely arbitrary.
1018    One must only ensure that a given VLAN is numbered consistently
1019    throughout a network and that different VLANs are given different
1020    numbers.  (That said, VLAN 0 is usually synonymous with a packet
1021    that has no VLAN header, and VLAN 4095 is reserved.)
1022
1023 ### Q: VLANs don't work.
1024
1025 A: Many drivers in Linux kernels before version 3.3 had VLAN-related
1026    bugs.  If you are having problems with VLANs that you suspect to be
1027    driver related, then you have several options:
1028
1029    - Upgrade to Linux 3.3 or later.
1030
1031    - Build and install a fixed version of the particular driver
1032      that is causing trouble, if one is available.
1033
1034    - Use a NIC whose driver does not have VLAN problems.
1035
1036    - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later
1037      that works around bugs in kernel drivers.  To enable VLAN
1038      splinters on interface eth0, use the command:
1039
1040        ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true
1041
1042      For VLAN splinters to be effective, Open vSwitch must know
1043      which VLANs are in use.  See the "VLAN splinters" section in
1044      the Interface table in ovs-vswitchd.conf.db(5) for details on
1045      how Open vSwitch infers in-use VLANs.
1046
1047      VLAN splinters increase memory use and reduce performance, so
1048      use them only if needed.
1049
1050    - Apply the "vlan workaround" patch from the XenServer kernel
1051      patch queue, build Open vSwitch against this patched kernel,
1052      and then use ovs-vlan-bug-workaround(8) to enable the VLAN
1053      workaround for each interface whose driver is buggy.
1054
1055      (This is a nontrivial exercise, so this option is included
1056      only for completeness.)
1057
1058    It is not always easy to tell whether a Linux kernel driver has
1059    buggy VLAN support.  The ovs-vlan-test(8) and ovs-test(8) utilities
1060    can help you test.  See their manpages for details.  Of the two
1061    utilities, ovs-test(8) is newer and more thorough, but
1062    ovs-vlan-test(8) may be easier to use.
1063
1064 ### Q: VLANs still don't work.  I've tested the driver so I know that it's OK.
1065
1066 A: Do you have VLANs enabled on the physical switch that OVS is
1067    attached to?  Make sure that the port is configured to trunk the
1068    VLAN or VLANs that you are using with OVS.
1069
1070 ### Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch
1071    and to its destination host, but OVS seems to drop incoming return
1072    traffic.
1073
1074 A: It's possible that you have the VLAN configured on your physical
1075    switch as the "native" VLAN.  In this mode, the switch treats
1076    incoming packets either tagged with the native VLAN or untagged as
1077    part of the native VLAN.  It may also send outgoing packets in the
1078    native VLAN without a VLAN tag.
1079
1080    If this is the case, you have two choices:
1081
1082    - Change the physical switch port configuration to tag packets
1083      it forwards to OVS with the native VLAN instead of forwarding
1084      them untagged.
1085
1086    - Change the OVS configuration for the physical port to a
1087      native VLAN mode.  For example, the following sets up a
1088      bridge with port eth0 in "native-tagged" mode in VLAN 9:
1089
1090          ovs-vsctl add-br br0
1091          ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged
1092
1093      In this situation, "native-untagged" mode will probably work
1094      equally well.  Refer to the documentation for the Port table
1095      in ovs-vswitchd.conf.db(5) for more information.
1096
1097 ### Q: I added a pair of VMs on different VLANs, like this:
1098
1099        ovs-vsctl add-br br0
1100        ovs-vsctl add-port br0 eth0
1101        ovs-vsctl add-port br0 tap0 tag=9
1102        ovs-vsctl add-port br0 tap1 tag=10
1103
1104     but the VMs can't access each other, the external network, or the
1105     Internet.
1106
1107 A: It is to be expected that the VMs can't access each other.  VLANs
1108    are a means to partition a network.  When you configured tap0 and
1109    tap1 as access ports for different VLANs, you indicated that they
1110    should be isolated from each other.
1111
1112    As for the external network and the Internet, it seems likely that
1113    the machines you are trying to access are not on VLAN 9 (or 10) and
1114    that the Internet is not available on VLAN 9 (or 10).
1115
1116 ### Q: I added a pair of VMs on the same VLAN, like this:
1117
1118        ovs-vsctl add-br br0
1119        ovs-vsctl add-port br0 eth0
1120        ovs-vsctl add-port br0 tap0 tag=9
1121        ovs-vsctl add-port br0 tap1 tag=9
1122
1123     The VMs can access each other, but not the external network or the
1124     Internet.
1125
1126 A: It seems likely that the machines you are trying to access in the
1127    external network are not on VLAN 9 and that the Internet is not
1128    available on VLAN 9.  Also, ensure VLAN 9 is set up as an allowed
1129    trunk VLAN on the upstream switch port to which eth0 is connected.
1130
1131 ### Q: Can I configure an IP address on a VLAN?
1132
1133 A: Yes.  Use an "internal port" configured as an access port.  For
1134    example, the following configures IP address 192.168.0.7 on VLAN 9.
1135    That is, OVS will forward packets from eth0 to 192.168.0.7 only if
1136    they have an 802.1Q header with VLAN 9.  Conversely, traffic
1137    forwarded from 192.168.0.7 to eth0 will be tagged with an 802.1Q
1138    header with VLAN 9:
1139
1140        ovs-vsctl add-br br0
1141        ovs-vsctl add-port br0 eth0
1142        ovs-vsctl add-port br0 vlan9 tag=9 -- set interface vlan9 type=internal
1143        ifconfig vlan9 192.168.0.7
1144
1145    See also the following question.
1146
1147 ### Q: I configured one IP address on VLAN 0 and another on VLAN 9, like
1148    this:
1149
1150        ovs-vsctl add-br br0
1151        ovs-vsctl add-port br0 eth0
1152        ifconfig br0 192.168.0.5
1153        ovs-vsctl add-port br0 vlan9 tag=9 -- set interface vlan9 type=internal
1154        ifconfig vlan9 192.168.0.9
1155
1156    but other hosts that are only on VLAN 0 can reach the IP address
1157    configured on VLAN 9.  What's going on?
1158
1159 A: RFC 1122 section 3.3.4.2 "Multihoming Requirements" describes two
1160    approaches to IP address handling in Internet hosts:
1161
1162    - In the "Strong ES Model", where an ES is a host ("End
1163      System"), an IP address is primarily associated with a
1164      particular interface.  The host discards packets that arrive
1165      on interface A if they are destined for an IP address that is
1166      configured on interface B.  The host never sends packets from
1167      interface A using a source address configured on interface B.
1168
1169    - In the "Weak ES Model", an IP address is primarily associated
1170      with a host.  The host accepts packets that arrive on any
1171      interface if they are destined for any of the host's IP
1172      addresses, even if the address is configured on some
1173      interface other than the one on which it arrived.  The host
1174      does not restrict itself to sending packets from an IP
1175      address associated with the originating interface.
1176
1177    Linux uses the weak ES model.  That means that when packets
1178    destined to the VLAN 9 IP address arrive on eth0 and are bridged to
1179    br0, the kernel IP stack accepts them there for the VLAN 9 IP
1180    address, even though they were not received on vlan9, the network
1181    device for vlan9.
1182
1183    To simulate the strong ES model on Linux, one may add iptables rule
1184    to filter packets based on source and destination address and
1185    adjust ARP configuration with sysctls.
1186
1187    BSD uses the strong ES model.
1188
1189 ### Q: My OpenFlow controller doesn't see the VLANs that I expect.
1190
1191 A: The configuration for VLANs in the Open vSwitch database (e.g. via
1192    ovs-vsctl) only affects traffic that goes through Open vSwitch's
1193    implementation of the OpenFlow "normal switching" action.  By
1194    default, when Open vSwitch isn't connected to a controller and
1195    nothing has been manually configured in the flow table, all traffic
1196    goes through the "normal switching" action.  But, if you set up
1197    OpenFlow flows on your own, through a controller or using ovs-ofctl
1198    or through other means, then you have to implement VLAN handling
1199    yourself.
1200
1201    You can use "normal switching" as a component of your OpenFlow
1202    actions, e.g. by putting "normal" into the lists of actions on
1203    ovs-ofctl or by outputting to OFPP_NORMAL from an OpenFlow
1204    controller.  In situations where this is not suitable, you can
1205    implement VLAN handling yourself, e.g.:
1206
1207    - If a packet comes in on an access port, and the flow table
1208      needs to send it out on a trunk port, then the flow can add
1209      the appropriate VLAN tag with the "mod_vlan_vid" action.
1210
1211    - If a packet comes in on a trunk port, and the flow table
1212      needs to send it out on an access port, then the flow can
1213      strip the VLAN tag with the "strip_vlan" action.
1214
1215 ### Q: I configured ports on a bridge as access ports with different VLAN
1216    tags, like this:
1217
1218        ovs-vsctl add-br br0
1219        ovs-vsctl set-controller br0 tcp:192.168.0.10:6653
1220        ovs-vsctl add-port br0 eth0
1221        ovs-vsctl add-port br0 tap0 tag=9
1222        ovs-vsctl add-port br0 tap1 tag=10
1223
1224    but the VMs running behind tap0 and tap1 can still communicate,
1225    that is, they are not isolated from each other even though they are
1226    on different VLANs.
1227
1228 A: Do you have a controller configured on br0 (as the commands above
1229    do)?  If so, then this is a variant on the previous question, "My
1230    OpenFlow controller doesn't see the VLANs that I expect," and you
1231    can refer to the answer there for more information.
1232
1233 ### Q: How MAC learning works with VLANs?
1234
1235 A: Open vSwitch implements Independent VLAN Learning (IVL) for
1236    OFPP_NORMAL action.  I.e. it logically has separate learning tables
1237    for each VLANs.
1238
1239
1240 VXLANs
1241 -----
1242
1243 ### Q: What's a VXLAN?
1244
1245 A: VXLAN stands for Virtual eXtensible Local Area Network, and is a means
1246    to solve the scaling challenges of VLAN networks in a multi-tenant
1247    environment. VXLAN is an overlay network which transports an L2 network
1248    over an existing L3 network. For more information on VXLAN, please see
1249    RFC 7348:
1250
1251    http://tools.ietf.org/html/rfc7348
1252
1253 ### Q: How much of the VXLAN protocol does Open vSwitch currently support?
1254
1255 A: Open vSwitch currently supports the framing format for packets on the
1256    wire. There is currently no support for the multicast aspects of VXLAN.
1257    To get around the lack of multicast support, it is possible to
1258    pre-provision MAC to IP address mappings either manually or from a
1259    controller.
1260
1261 ### Q: What destination UDP port does the VXLAN implementation in Open vSwitch
1262    use?
1263
1264 A: By default, Open vSwitch will use the assigned IANA port for VXLAN, which
1265    is 4789. However, it is possible to configure the destination UDP port
1266    manually on a per-VXLAN tunnel basis. An example of this configuration is
1267    provided below.
1268
1269        ovs-vsctl add-br br0
1270        ovs-vsctl add-port br0 vxlan1 -- set interface vxlan1
1271        type=vxlan options:remote_ip=192.168.1.2 options:key=flow
1272        options:dst_port=8472
1273
1274
1275 Using OpenFlow (Manually or Via Controller)
1276 -------------------------------------------
1277
1278 ### Q: What versions of OpenFlow does Open vSwitch support?
1279
1280 A: The following table lists the versions of OpenFlow supported by
1281    each version of Open vSwitch:
1282
1283        Open vSwitch      OF1.0  OF1.1  OF1.2  OF1.3  OF1.4  OF1.5
1284        ###============   =====  =====  =====  =====  =====  =====
1285        1.9 and earlier    yes    ---    ---    ---    ---    ---
1286        1.10               yes    ---    [*]    [*]    ---    ---
1287        1.11               yes    ---    [*]    [*]    ---    ---
1288        2.0                yes    [*]    [*]    [*]    ---    ---
1289        2.1                yes    [*]    [*]    [*]    ---    ---
1290        2.2                yes    [*]    [*]    [*]    [%]    [*]
1291        2.3                yes    yes    yes    yes    [*]    [*]
1292
1293        [*] Supported, with one or more missing features.
1294        [%] Experimental, unsafe implementation.
1295
1296    Open vSwitch 2.3 enables OpenFlow 1.0, 1.1, 1.2, and 1.3 by default
1297    in ovs-vswitchd.  In Open vSwitch 1.10 through 2.2, OpenFlow 1.1,
1298    1.2, and 1.3 must be enabled manually in ovs-vswitchd.  OpenFlow
1299    1.4 and 1.5 are also supported, with missing features, in Open
1300    vSwitch 2.3 and later, but not enabled by default.  In any case,
1301    the user may override the default:
1302
1303    - To enable OpenFlow 1.0, 1.1, 1.2, and 1.3 on bridge br0:
1304
1305      ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13
1306
1307    - To enable OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 on bridge br0:
1308
1309      ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15
1310
1311    - To enable only OpenFlow 1.0 on bridge br0:
1312
1313      ovs-vsctl set bridge br0 protocols=OpenFlow10
1314
1315    All current versions of ovs-ofctl enable only OpenFlow 1.0 by
1316    default.  Use the -O option to enable support for later versions of
1317    OpenFlow in ovs-ofctl.  For example:
1318
1319        ovs-ofctl -O OpenFlow13 dump-flows br0
1320
1321    (Open vSwitch 2.2 had an experimental implementation of OpenFlow
1322    1.4 that could cause crashes.  We don't recommend enabling it.)
1323
1324    [OPENFLOW-1.1+.md] in the Open vSwitch source tree tracks support for
1325    OpenFlow 1.1 and later features.  When support for OpenFlow 1.4 and
1326    1.5 is solidly implemented, Open vSwitch will enable those version
1327    by default.  Also, the OpenFlow 1.5 specification is still under
1328    development and thus subject to change.
1329
1330 ### Q: Does Open vSwitch support MPLS?
1331
1332 A: Before version 1.11, Open vSwitch did not support MPLS.  That is,
1333    these versions can match on MPLS Ethernet types, but they cannot
1334    match, push, or pop MPLS labels, nor can they look past MPLS labels
1335    into the encapsulated packet.
1336
1337    Open vSwitch versions 1.11, 2.0, and 2.1 have very minimal support
1338    for MPLS.  With the userspace datapath only, these versions can
1339    match, push, or pop a single MPLS label, but they still cannot look
1340    past MPLS labels (even after popping them) into the encapsulated
1341    packet.  Kernel datapath support is unchanged from earlier
1342    versions.
1343
1344    Open vSwitch version 2.3 can match, push, or pop a single MPLS
1345    label and look past the MPLS label into the encapsulated packet.
1346    Both userspace and kernel datapaths will be supported, but MPLS
1347    processing always happens in userspace either way, so kernel
1348    datapath performance will be disappointing.
1349
1350    Open vSwitch version 2.4 can match, push, or pop up to 3 MPLS
1351    labels and look past the MPLS label into the encapsulated packet.
1352    It will have kernel support for MPLS, yielding improved
1353    performance.
1354
1355 ### Q: I'm getting "error type 45250 code 0".  What's that?
1356
1357 A: This is a Open vSwitch extension to OpenFlow error codes.  Open
1358    vSwitch uses this extension when it must report an error to an
1359    OpenFlow controller but no standard OpenFlow error code is
1360    suitable.
1361
1362    Open vSwitch logs the errors that it sends to controllers, so the
1363    easiest thing to do is probably to look at the ovs-vswitchd log to
1364    find out what the error was.
1365
1366    If you want to dissect the extended error message yourself, the
1367    format is documented in include/openflow/nicira-ext.h in the Open
1368    vSwitch source distribution.  The extended error codes are
1369    documented in lib/ofp-errors.h.
1370
1371 Q1: Some of the traffic that I'd expect my OpenFlow controller to see
1372     doesn't actually appear through the OpenFlow connection, even
1373     though I know that it's going through.
1374 Q2: Some of the OpenFlow flows that my controller sets up don't seem
1375     to apply to certain traffic, especially traffic between OVS and
1376     the controller itself.
1377
1378 A: By default, Open vSwitch assumes that OpenFlow controllers are
1379    connected "in-band", that is, that the controllers are actually
1380    part of the network that is being controlled.  In in-band mode,
1381    Open vSwitch sets up special "hidden" flows to make sure that
1382    traffic can make it back and forth between OVS and the controllers.
1383    These hidden flows are higher priority than any flows that can be
1384    set up through OpenFlow, and they are not visible through normal
1385    OpenFlow flow table dumps.
1386
1387    Usually, the hidden flows are desirable and helpful, but
1388    occasionally they can cause unexpected behavior.  You can view the
1389    full OpenFlow flow table, including hidden flows, on bridge br0
1390    with the command:
1391
1392        ovs-appctl bridge/dump-flows br0
1393
1394    to help you debug.  The hidden flows are those with priorities
1395    greater than 65535 (the maximum priority that can be set with
1396    OpenFlow).
1397
1398    The DESIGN file at the top level of the Open vSwitch source
1399    distribution describes the in-band model in detail.
1400
1401    If your controllers are not actually in-band (e.g. they are on
1402    localhost via 127.0.0.1, or on a separate network), then you should
1403    configure your controllers in "out-of-band" mode.  If you have one
1404    controller on bridge br0, then you can configure out-of-band mode
1405    on it with:
1406
1407        ovs-vsctl set controller br0 connection-mode=out-of-band
1408
1409 ### Q: I configured all my controllers for out-of-band control mode but
1410    "ovs-appctl bridge/dump-flows" still shows some hidden flows.
1411
1412 A: You probably have a remote manager configured (e.g. with "ovs-vsctl
1413    set-manager").  By default, Open vSwitch assumes that managers need
1414    in-band rules set up on every bridge.  You can disable these rules
1415    on bridge br0 with:
1416
1417        ovs-vsctl set bridge br0 other-config:disable-in-band=true
1418
1419    This actually disables in-band control entirely for the bridge, as
1420    if all the bridge's controllers were configured for out-of-band
1421    control.
1422
1423 ### Q: My OpenFlow controller doesn't see the VLANs that I expect.
1424
1425 A: See answer under "VLANs", above.
1426
1427 ### Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop"
1428    but I got a funny message like this:
1429
1430        ofp_util|INFO|normalization changed ofp_match, details:
1431        ofp_util|INFO| pre: nw_dst=192.168.0.1
1432        ofp_util|INFO|post:
1433
1434    and when I ran "ovs-ofctl dump-flows br0" I saw that my nw_dst
1435    match had disappeared, so that the flow ends up matching every
1436    packet.
1437
1438 A: The term "normalization" in the log message means that a flow
1439    cannot match on an L3 field without saying what L3 protocol is in
1440    use.  The "ovs-ofctl" command above didn't specify an L3 protocol,
1441    so the L3 field match was dropped.
1442
1443    In this case, the L3 protocol could be IP or ARP.  A correct
1444    command for each possibility is, respectively:
1445
1446        ovs-ofctl add-flow br0 ip,nw_dst=192.168.0.1,actions=drop
1447
1448    and
1449
1450        ovs-ofctl add-flow br0 arp,nw_dst=192.168.0.1,actions=drop
1451
1452    Similarly, a flow cannot match on an L4 field without saying what
1453    L4 protocol is in use.  For example, the flow match "tp_src=1234"
1454    is, by itself, meaningless and will be ignored.  Instead, to match
1455    TCP source port 1234, write "tcp,tp_src=1234", or to match UDP
1456    source port 1234, write "udp,tp_src=1234".
1457
1458 ### Q: How can I figure out the OpenFlow port number for a given port?
1459
1460 A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to
1461    respond with an OFPT_FEATURES_REPLY that, among other information,
1462    includes a mapping between OpenFlow port names and numbers.  From a
1463    command prompt, "ovs-ofctl show br0" makes such a request and
1464    prints the response for switch br0.
1465
1466    The Interface table in the Open vSwitch database also maps OpenFlow
1467    port names to numbers.  To print the OpenFlow port number
1468    associated with interface eth0, run:
1469
1470        ovs-vsctl get Interface eth0 ofport
1471
1472    You can print the entire mapping with:
1473
1474        ovs-vsctl -- --columns=name,ofport list Interface
1475
1476    but the output mixes together interfaces from all bridges in the
1477    database, so it may be confusing if more than one bridge exists.
1478
1479    In the Open vSwitch database, ofport value -1 means that the
1480    interface could not be created due to an error.  (The Open vSwitch
1481    log should indicate the reason.)  ofport value [] (the empty set)
1482    means that the interface hasn't been created yet.  The latter is
1483    normally an intermittent condition (unless ovs-vswitchd is not
1484    running).
1485
1486 ### Q: I added some flows with my controller or with ovs-ofctl, but when I
1487    run "ovs-dpctl dump-flows" I don't see them.
1488
1489 A: ovs-dpctl queries a kernel datapath, not an OpenFlow switch.  It
1490    won't display the information that you want.  You want to use
1491    "ovs-ofctl dump-flows" instead.
1492
1493 ### Q: It looks like each of the interfaces in my bonded port shows up
1494    as an individual OpenFlow port.  Is that right?
1495
1496 A: Yes, Open vSwitch makes individual bond interfaces visible as
1497    OpenFlow ports, rather than the bond as a whole.  The interfaces
1498    are treated together as a bond for only a few purposes:
1499
1500    - Sending a packet to the OFPP_NORMAL port.  (When an OpenFlow
1501      controller is not configured, this happens implicitly to
1502      every packet.)
1503
1504    - Mirrors configured for output to a bonded port.
1505
1506    It would make a lot of sense for Open vSwitch to present a bond as
1507    a single OpenFlow port.  If you want to contribute an
1508    implementation of such a feature, please bring it up on the Open
1509    vSwitch development mailing list at dev@openvswitch.org.
1510
1511 ### Q: I have a sophisticated network setup involving Open vSwitch, VMs or
1512    multiple hosts, and other components.  The behavior isn't what I
1513    expect.  Help!
1514
1515 A: To debug network behavior problems, trace the path of a packet,
1516    hop-by-hop, from its origin in one host to a remote host.  If
1517    that's correct, then trace the path of the response packet back to
1518    the origin.
1519
1520    Usually a simple ICMP echo request and reply ("ping") packet is
1521    good enough.  Start by initiating an ongoing "ping" from the origin
1522    host to a remote host.  If you are tracking down a connectivity
1523    problem, the "ping" will not display any successful output, but
1524    packets are still being sent.  (In this case the packets being sent
1525    are likely ARP rather than ICMP.)
1526
1527    Tools available for tracing include the following:
1528
1529    - "tcpdump" and "wireshark" for observing hops across network
1530      devices, such as Open vSwitch internal devices and physical
1531      wires.
1532
1533    - "ovs-appctl dpif/dump-flows <br>" in Open vSwitch 1.10 and
1534      later or "ovs-dpctl dump-flows <br>" in earlier versions.
1535      These tools allow one to observe the actions being taken on
1536      packets in ongoing flows.
1537
1538      See ovs-vswitchd(8) for "ovs-appctl dpif/dump-flows"
1539      documentation, ovs-dpctl(8) for "ovs-dpctl dump-flows"
1540      documentation, and "Why are there so many different ways to
1541      dump flows?" above for some background.
1542
1543    - "ovs-appctl ofproto/trace" to observe the logic behind how
1544      ovs-vswitchd treats packets.  See ovs-vswitchd(8) for
1545      documentation.  You can out more details about a given flow
1546      that "ovs-dpctl dump-flows" displays, by cutting and pasting
1547      a flow from the output into an "ovs-appctl ofproto/trace"
1548      command.
1549
1550    - SPAN, RSPAN, and ERSPAN features of physical switches, to
1551      observe what goes on at these physical hops.
1552
1553    Starting at the origin of a given packet, observe the packet at
1554    each hop in turn.  For example, in one plausible scenario, you
1555    might:
1556
1557    1. "tcpdump" the "eth" interface through which an ARP egresses
1558       a VM, from inside the VM.
1559
1560    2. "tcpdump" the "vif" or "tap" interface through which the ARP
1561       ingresses the host machine.
1562
1563    3. Use "ovs-dpctl dump-flows" to spot the ARP flow and observe
1564       the host interface through which the ARP egresses the
1565       physical machine.  You may need to use "ovs-dpctl show" to
1566       interpret the port numbers.  If the output seems surprising,
1567       you can use "ovs-appctl ofproto/trace" to observe details of
1568       how ovs-vswitchd determined the actions in the "ovs-dpctl
1569       dump-flows" output.
1570
1571    4. "tcpdump" the "eth" interface through which the ARP egresses
1572       the physical machine.
1573
1574    5. "tcpdump" the "eth" interface through which the ARP
1575       ingresses the physical machine, at the remote host that
1576       receives the ARP.
1577
1578    6. Use "ovs-dpctl dump-flows" to spot the ARP flow on the
1579       remote host that receives the ARP and observe the VM "vif"
1580       or "tap" interface to which the flow is directed.  Again,
1581       "ovs-dpctl show" and "ovs-appctl ofproto/trace" might help.
1582
1583    7. "tcpdump" the "vif" or "tap" interface to which the ARP is
1584       directed.
1585
1586    8. "tcpdump" the "eth" interface through which the ARP
1587       ingresses a VM, from inside the VM.
1588
1589    It is likely that during one of these steps you will figure out the
1590    problem.  If not, then follow the ARP reply back to the origin, in
1591    reverse.
1592
1593 ### Q: How do I make a flow drop packets?
1594
1595 A: To drop a packet is to receive it without forwarding it.  OpenFlow
1596    explicitly specifies forwarding actions.  Thus, a flow with an
1597    empty set of actions does not forward packets anywhere, causing
1598    them to be dropped.  You can specify an empty set of actions with
1599    "actions=" on the ovs-ofctl command line.  For example:
1600
1601        ovs-ofctl add-flow br0 priority=65535,actions=
1602
1603    would cause every packet entering switch br0 to be dropped.
1604
1605    You can write "drop" explicitly if you like.  The effect is the
1606    same.  Thus, the following command also causes every packet
1607    entering switch br0 to be dropped:
1608
1609        ovs-ofctl add-flow br0 priority=65535,actions=drop
1610
1611    "drop" is not an action, either in OpenFlow or Open vSwitch.
1612    Rather, it is only a way to say that there are no actions.
1613
1614 ### Q: I added a flow to send packets out the ingress port, like this:
1615
1616        ovs-ofctl add-flow br0 in_port=2,actions=2
1617
1618    but OVS drops the packets instead.
1619
1620 A: Yes, OpenFlow requires a switch to ignore attempts to send a packet
1621    out its ingress port.  The rationale is that dropping these packets
1622    makes it harder to loop the network.  Sometimes this behavior can
1623    even be convenient, e.g. it is often the desired behavior in a flow
1624    that forwards a packet to several ports ("floods" the packet).
1625
1626    Sometimes one really needs to send a packet out its ingress port
1627    ("hairpin"). In this case, output to OFPP_IN_PORT, which in
1628    ovs-ofctl syntax is expressed as just "in_port", e.g.:
1629
1630        ovs-ofctl add-flow br0 in_port=2,actions=in_port
1631
1632    This also works in some circumstances where the flow doesn't match
1633    on the input port.  For example, if you know that your switch has
1634    five ports numbered 2 through 6, then the following will send every
1635    received packet out every port, even its ingress port:
1636
1637        ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
1638
1639    or, equivalently:
1640
1641        ovs-ofctl add-flow br0 actions=all,in_port
1642
1643    Sometimes, in complicated flow tables with multiple levels of
1644    "resubmit" actions, a flow needs to output to a particular port
1645    that may or may not be the ingress port.  It's difficult to take
1646    advantage of OFPP_IN_PORT in this situation.  To help, Open vSwitch
1647    provides, as an OpenFlow extension, the ability to modify the
1648    in_port field.  Whatever value is currently in the in_port field is
1649    the port to which outputs will be dropped, as well as the
1650    destination for OFPP_IN_PORT.  This means that the following will
1651    reliably output to port 2 or to ports 2 through 6, respectively:
1652
1653        ovs-ofctl add-flow br0 in_port=2,actions=load:0->NXM_OF_IN_PORT[],2
1654        ovs-ofctl add-flow br0 actions=load:0->NXM_OF_IN_PORT[],2,3,4,5,6
1655
1656    If the input port is important, then one may save and restore it on
1657    the stack:
1658
1659         ovs-ofctl add-flow br0 actions=push:NXM_OF_IN_PORT[],\
1660                                        load:0->NXM_OF_IN_PORT[],\
1661                                        2,3,4,5,6,\
1662                                        pop:NXM_OF_IN_PORT[]
1663
1664 ### Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2
1665    on port 2.  I set up flows to forward only traffic destined to the
1666    other host and drop other traffic, like this:
1667
1668       priority=5,in_port=1,ip,nw_dst=192.168.0.2,actions=2
1669       priority=5,in_port=2,ip,nw_dst=192.168.0.1,actions=1
1670       priority=0,actions=drop
1671
1672    But it doesn't work--I don't get any connectivity when I do this.
1673    Why?
1674
1675 A: These flows drop the ARP packets that IP hosts use to establish IP
1676    connectivity over Ethernet.  To solve the problem, add flows to
1677    allow ARP to pass between the hosts:
1678
1679       priority=5,in_port=1,arp,actions=2
1680       priority=5,in_port=2,arp,actions=1
1681
1682    This issue can manifest other ways, too.  The following flows that
1683    match on Ethernet addresses instead of IP addresses will also drop
1684    ARP packets, because ARP requests are broadcast instead of being
1685    directed to a specific host:
1686
1687       priority=5,in_port=1,dl_dst=54:00:00:00:00:02,actions=2
1688       priority=5,in_port=2,dl_dst=54:00:00:00:00:01,actions=1
1689       priority=0,actions=drop
1690
1691    The solution already described above will also work in this case.
1692    It may be better to add flows to allow all multicast and broadcast
1693    traffic:
1694
1695       priority=5,in_port=1,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=2
1696       priority=5,in_port=2,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=1
1697
1698 ### Q: My bridge disconnects from my controller on add-port/del-port.
1699
1700 A: Reconfiguring your bridge can change your bridge's datapath-id because
1701    Open vSwitch generates datapath-id from the MAC address of one of its ports.
1702    In that case, Open vSwitch disconnects from controllers because there's
1703    no graceful way to notify controllers about the change of datapath-id.
1704
1705    To avoid the behaviour, you can configure datapath-id manually.
1706
1707       ovs-vsctl set bridge br0 other-config:datapath-id=0123456789abcdef
1708
1709 ### Q: My controller is getting errors about "buffers".  What's going on?
1710
1711 A: When a switch sends a packet to an OpenFlow controller using a
1712    "packet-in" message, it can also keep a copy of that packet in a
1713    "buffer", identified by a 32-bit integer "buffer_id".  There are
1714    two advantages to buffering.  First, when the controller wants to
1715    tell the switch to do something with the buffered packet (with a
1716    "packet-out" OpenFlow request), it does not need to send another
1717    copy of the packet back across the OpenFlow connection, which
1718    reduces the bandwidth cost of the connection and improves latency.
1719    This enables the second advantage: the switch can optionally send
1720    only the first part of the packet to the controller (assuming that
1721    the switch only needs to look at the first few bytes of the
1722    packet), further reducing bandwidth and improving latency.
1723
1724    However, buffering introduces some issues of its own.  First, any
1725    switch has limited resources, so if the controller does not use a
1726    buffered packet, the switch has to decide how long to keep it
1727    buffered.  When many packets are sent to a controller and buffered,
1728    Open vSwitch can discard buffered packets that the controller has
1729    not used after as little as 5 seconds.  This means that
1730    controllers, if they make use of packet buffering, should use the
1731    buffered packets promptly.  (This includes sending a "packet-out"
1732    with no actions if the controller does not want to do anything with
1733    a buffered packet, to clear the packet buffer and effectively
1734    "drop" its packet.)
1735
1736    Second, packet buffers are one-time-use, meaning that a controller
1737    cannot use a single packet buffer in two or more "packet-out"
1738    commands.  Open vSwitch will respond with an error to the second
1739    and subsequent "packet-out"s in such a case.
1740
1741    Finally, a common error early in controller development is to try
1742    to use buffer_id 0 in a "packet-out" message as if 0 represented
1743    "no buffered packet".  This is incorrect usage: the buffer_id with
1744    this meaning is actually 0xffffffff.
1745
1746    ovs-vswitchd(8) describes some details of Open vSwitch packet
1747    buffering that the OpenFlow specification requires implementations
1748    to document.
1749
1750
1751 Development
1752 -----------
1753
1754 ### Q: How do I implement a new OpenFlow message?
1755
1756 A: Add your new message to "enum ofpraw" and "enum ofptype" in
1757    lib/ofp-msgs.h, following the existing pattern.  Then recompile and
1758    fix all of the new warnings, implementing new functionality for the
1759    new message as needed.  (If you configure with --enable-Werror, as
1760    described in [INSTALL.md], then it is impossible to miss any warnings.)
1761
1762    If you need to add an OpenFlow vendor extension message for a
1763    vendor that doesn't yet have any extension messages, then you will
1764    also need to edit build-aux/extract-ofp-msgs.
1765
1766 ### Q: How do I add support for a new field or header?
1767
1768 A: Add new members for your field to "struct flow" in lib/flow.h, and
1769    add new enumerations for your new field to "enum mf_field_id" in
1770    lib/meta-flow.h, following the existing pattern.  Also, add support
1771    to miniflow_extract() in lib/flow.c for extracting your new field
1772    from a packet into struct miniflow.  Then recompile and fix all of
1773    the new warnings, implementing new functionality for the new field
1774    or header as needed.  (If you configure with --enable-Werror, as
1775    described in [INSTALL.md], then it is impossible to miss any
1776    warnings.)
1777
1778    If you want kernel datapath support for your new field, you also
1779    need to modify the kernel module for the operating systems you are
1780    interested in.  This isn't mandatory, since fields understood only
1781    by userspace work too (with a performance penalty), so it's
1782    reasonable to start development without it.  If you implement
1783    kernel module support for Linux, then the Linux kernel "netdev"
1784    mailing list is the place to submit that support first; please read
1785    up on the Linux kernel development process separately.  The Windows
1786    datapath kernel module support, on the other hand, is maintained
1787    within the OVS tree, so patches for that can go directly to
1788    ovs-dev.
1789
1790 ### Q: How do I add support for a new OpenFlow action?
1791
1792 A: Add your new action to "enum ofp_raw_action_type" in
1793    lib/ofp-actions.c, following the existing pattern.  Then recompile
1794    and fix all of the new warnings, implementing new functionality for
1795    the new action as needed.  (If you configure with --enable-Werror,
1796    as described in [INSTALL.md], then it is impossible to miss any
1797    warnings.)
1798
1799    If you need to add an OpenFlow vendor extension action for a vendor
1800    that doesn't yet have any extension actions, then you will also
1801    need to edit build-aux/extract-ofp-actions.
1802
1803
1804 Contact
1805 -------
1806
1807 bugs@openvswitch.org
1808 http://openvswitch.org/
1809
1810 [PORTING.md]:PORTING.md
1811 [WHY-OVS.md]:WHY-OVS.md
1812 [INSTALL.md]:INSTALL.md
1813 [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md