FAQ

   1                  Open vSwitch <http://openvswitch.org>
   2
   3 Frequently Asked Questions
   4 ==========================
   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 environments.  A
  13    vswitch forwards traffic between different VMs on the same physical host
  14    and also forwards traffic between VMs and the physical network.  Open
  15    vSwitch supports standard management interfaces (e.g. sFlow, NetFlow,
  16    RSPAN, CLI), and is open to programmatic extension and control using
  17    OpenFlow and the OVSDB management protocol.
  18
  19    Open vSwitch as designed to be compatible with modern switching
  20    chipsets.  This means that it can be ported to existing high-fanout
  21    switches allowing the same flexible control of the physical
  22    infrastructure as the virtual infrastructure.  It also means that
  23    Open vSwitch will be able to take advantage of on-NIC switching
  24    chipsets as their functionality matures.
  25
  26 Q: What virtualization platforms can use Open vSwitch?
  27
  28 A: Open vSwitch can currently run on any Linux-based virtualization
  29    platform (kernel 2.6.18 and newer), including: KVM, VirtualBox, Xen,
  30    Xen Cloud Platform, XenServer. As of Linux 3.3 it is part of the
  31    mainline kernel.  The bulk of the code is written in platform-
  32    independent C and is easily ported to other environments.  We welcome
  33    inquires about integrating Open vSwitch with other virtualization
  34    platforms.
  35
  36 Q: How can I try Open vSwitch?
  37
  38 A: Open vSwitch is as source code to be built on a Linux system.  You
  39    can build and experiment with Open vSwitch on any Linux machine.
  40    Packages for various Linux distributions are underway and will be linked
  41    to from this website as they materialize.
  42
  43    You may also download and run a virtualization platform that already
  44    has Open vSwitch integrated.  For example, download the ISO for Xen
  45    Cloud Platform.  Be aware that the version integrated with a
  46    particular platform may not be the most recent Open vSwitch release.
  47
  48 Q: Why would I use Open vSwitch instead of the Linux bridge?
  49
  50 A: Open vSwitch is specially designed to make it easier to manage VM
  51    network configuration and monitoring state spread across many
  52    physical hosts in dynamic virtualized environments.  Please see
  53    WHY-OVS for a more detailed description of how Open vSwitch relates
  54    to the Linux Bridge.
  55
  56 Q: How is Open vSwitch related to distributed virtual switches like the
  57    VMware vNetwork distributed switch or the Cisco Nexus 1000V?
  58
  59 A: Distributed vswitch applications (e.g., VMware vNetwork distributed
  60    switch, Cisco Nexus 1000V) provide a centralized way to configure and
  61    monitor the network state of VMs that are spread across many physical
  62    hosts.  Open vSwitch is not a distributed vswitch itself, rather it
  63    runs on each physical host and supports remote management in a way
  64    that makes it easier for developers of virtualization/cloud
  65    management platforms to offer distributed vswitch capabilities.
  66
  67    To aid in distribution, Open vSwitch provides two open protocols that
  68    are specially designed for remote management in virtualized network
  69    environments: OpenFlow, which exposes flow-based forwarding state,
  70    and the OVSDB management protocol, which exposes switch port state.
  71    In addition to the switch implementation itself, Open vSwitch
  72    includes tools (ovs-controller, ovs-ofctl, ovs-vsctl) that developers
  73    can script and extend to provide distributed vswitch capabilities
  74    that are closely integrated with their virtualization management
  75    platform.
  76
  77 Q: Why doesn't Open vSwitch support distribution?
  78
  79 A: Open vSwitch is intended to be a useful component for building
  80    flexible network infrastructure. There are many different approaches
  81    to distribution which balance trade-offs between simplicity,
  82    scalability, hardware compatibility, convergence times, logical
  83    forwarding model, etc. The goal of Open vSwitch is to be able to
  84    support all as a primitive building block rather than choose a
  85    particular point in the distributed design space.
  86
  87 Q: What does it mean for an Open vSwitch release to be "stable"?
  88
  89 A: A stable Open vSwitch release is code that has been through a
  90    comprehensive testing process and is suitable for production use.
  91    Planned stable releases will occur several times a year.  If a
  92    significant bug is identified in a stable release, we will provide an
  93    updated stable release that includes the fix.  Developers looking to
  94    test the latest Open vSwitch code can use an "unstable" release or
  95    directly access the code via git.
  96
  97 Q: How can I contribute to the Open vSwitch Community?
  98
  99 A: You can start by joining the mailing lists and helping to answer
 100    questions.  You can also suggest improvements to documentation or offer
 101    to write a configuration cookbook entry.
 102
 103    If you have a feature or bug you would like to work on send a mail to
 104    dev mailing list.
 105
 106
 107 Configuration Problems
 108 ----------------------
 109
 110 Q: I created a bridge and added my Ethernet port to it, using commands
 111    like these:
 112
 113        ovs-vsctl add-br br0
 114        ovs-vsctl add-port br0 eth0
 115
 116    and as soon as I ran the "add-port" command I lost all connectivity
 117    through eth0.  Help!
 118
 119 A: A physical Ethernet device that is part of an Open vSwitch bridge
 120    should not have an IP address.  If one does, then that IP address
 121    will not be fully functional.
 122
 123    You can restore functionality by moving the IP address to an Open
 124    vSwitch "internal" device, such as the network device named after
 125    the bridge itself.  For example, assuming that eth0's IP address is
 126    192.168.128.5, you could run the commands below to fix up the
 127    situation:
 128
 129        ifconfig eth0 0.0.0.0
 130        ifconfig br0 192.168.128.5
 131
 132    (If your only connection to the machine running OVS is through the
 133    IP address in question, then you would want to run all of these
 134    commands on a single command line, or put them into a script.)  If
 135    there were any additional routes assigned to eth0, then you would
 136    also want to use commands to adjust these routes to go through br0.
 137
 138    If you use DHCP to obtain an IP address, then you should kill the
 139    DHCP client that was listening on the physical Ethernet interface
 140    (e.g. eth0) and start one listening on the internal interface
 141    (e.g. br0).  You might still need to manually clear the IP address
 142    from the physical interface (e.g. with "ifconfig eth0 0.0.0.0").
 143
 144    There is no compelling reason why Open vSwitch must work this way.
 145    However, this is the way that the Linux kernel bridge module has
 146    always worked, so it's a model that those accustomed to Linux
 147    bridging are already used to.  Also, the model that most people
 148    expect is not implementable without kernel changes on all the
 149    versions of Linux that Open vSwitch supports.
 150
 151    By the way, this issue is not specific to physical Ethernet
 152    devices.  It applies to all network devices except Open vswitch
 153    "internal" devices.
 154
 155 Q: I created a bridge and added a couple of Ethernet ports to it,
 156    using commands like these:
 157
 158        ovs-vsctl add-br br0
 159        ovs-vsctl add-port br0 eth0
 160        ovs-vsctl add-port br0 eth1
 161
 162    and now my network seems to have melted: connectivity is unreliable
 163    (even connectivity that doesn't go through Open vSwitch), all the
 164    LEDs on my physical switches are blinking, wireshark shows
 165    duplicated packets, and CPU usage is very high.
 166
 167 A: More than likely, you've looped your network.  Probably, eth0 and
 168    eth1 are connected to the same physical Ethernet switch.  This
 169    yields a scenario where OVS receives a broadcast packet on eth0 and
 170    sends it out on eth1, then the physical switch connected to eth1
 171    sends the packet back on eth0, and so on forever.  More complicated
 172    scenarios, involving a loop through multiple switches, are possible
 173    too.
 174
 175    The solution depends on what you are trying to do:
 176
 177        - If you added eth0 and eth1 to get higher bandwidth or higher
 178          reliability between OVS and your physical Ethernet switch,
 179          use a bond.  The following commands create br0 and then add
 180          eth0 and eth1 as a bond:
 181
 182              ovs-vsctl add-br br0
 183              ovs-vsctl add-bond br0 bond0 eth0 eth1
 184
 185          Bonds have tons of configuration options.  Please read the
 186          documentation on the Port table in ovs-vswitchd.conf.db(5)
 187          for all the details.
 188
 189        - Perhaps you don't actually need eth0 and eth1 to be on the
 190          same bridge.  For example, if you simply want to be able to
 191          connect each of them to virtual machines, then you can put
 192          each of them on a bridge of its own:
 193
 194              ovs-vsctl add-br br0
 195              ovs-vsctl add-port br0 eth0
 196
 197              ovs-vsctl add-br br1
 198              ovs-vsctl add-port br1 eth1
 199
 200          and then connect VMs to br0 and br1.  (A potential
 201          disadvantage is that traffic cannot directly pass between br0
 202          and br1.  Instead, it will go out eth0 and come back in eth1,
 203          or vice versa.)
 204
 205        - If you have a redundant or complex network topology and you
 206          want to prevent loops, turn on spanning tree protocol (STP).
 207          The following commands create br0, enable STP, and add eth0
 208          and eth1 to the bridge.  The order is important because you
 209          don't want have to have a loop in your network even
 210          transiently:
 211
 212              ovs-vsctl add-br br0
 213              ovs-vsctl set bridge br0 stp_enable=true
 214              ovs-vsctl add-port br0 eth0
 215              ovs-vsctl add-port br0 eth1
 216
 217          The Open vSwitch implementation of STP is not well tested.
 218          Please report any bugs you observe, but if you'd rather avoid
 219          acting as a beta tester then another option might be your
 220          best shot.
 221
 222 Q: I can't seem to use Open vSwitch in a wireless network.
 223
 224 A: Wireless base stations generally only allow packets with the source
 225    MAC address of NIC that completed the initial handshake.
 226    Therefore, without MAC rewriting, only a single device can
 227    communicate over a single wireless link.
 228
 229    This isn't specific to Open vSwitch, it's enforced by the access
 230    point, so the same problems will show up with the Linux bridge or
 231    any other way to do bridging.
 232
 233
 234 VLANs
 235 -----
 236
 237 Q: VLANs don't work.
 238
 239 A: Many drivers in Linux kernels before version 3.3 had VLAN-related
 240    bugs.  If you are having problems with VLANs that you suspect to be
 241    driver related, then you have several options:
 242
 243        - Upgrade to Linux 3.3 or later.
 244
 245        - Build and install a fixed version of the particular driver
 246          that is causing trouble, if one is available.
 247
 248        - Use a NIC whose driver does not have VLAN problems.
 249
 250        - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later
 251          that works around bugs in kernel drivers.  To enable VLAN
 252          splinters on interface eth0, use the command:
 253
 254              ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true
 255
 256          For VLAN splinters to be effective, Open vSwitch must know
 257          which VLANs are in use.  See the "VLAN splinters" section in
 258          the Interface table in ovs-vswitchd.conf.db(5) for details on
 259          how Open vSwitch infers in-use VLANs.
 260
 261          VLAN splinters increase memory use and reduce performance, so
 262          use them only if needed.
 263
 264        - Apply the "vlan workaround" patch from the XenServer kernel
 265          patch queue, build Open vSwitch against this patched kernel,
 266          and then use ovs-vlan-bug-workaround(8) to enable the VLAN
 267          workaround for each interface whose driver is buggy.
 268
 269          (This is a nontrivial exercise, so this option is included
 270          only for completeness.)
 271
 272    It is not always easy to tell whether a Linux kernel driver has
 273    buggy VLAN support.  The ovs-vlan-test(8) and ovs-test(8) utilities
 274    can help you test.  See their manpages for details.  Of the two
 275    utilities, ovs-test(8) is newer and more thorough, but
 276    ovs-vlan-test(8) may be easier to use.
 277
 278 Q: VLANs still don't work.  I've tested the driver so I know that it's OK.
 279
 280 A: Do you have VLANs enabled on the physical switch that OVS is
 281    attached to?  Make sure that the port is configured to trunk the
 282    VLAN or VLANs that you are using with OVS.
 283
 284 Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch
 285    and to its destination host, but OVS seems to drop incoming return
 286    traffic.
 287
 288 A: It's possible that you have the VLAN configured on your physical
 289    switch as the "native" VLAN.  In this mode, the switch treats
 290    incoming packets either tagged with the native VLAN or untagged as
 291    part of the native VLAN.  It may also send outgoing packets in the
 292    native VLAN without a VLAN tag.
 293
 294    If this is the case, you have two choices:
 295
 296        - Change the physical switch port configuration to tag packets
 297          it forwards to OVS with the native VLAN instead of forwarding
 298          them untagged.
 299
 300        - Change the OVS configuration for the physical port to a
 301          native VLAN mode.  For example, the following sets up a
 302          bridge with port eth0 in "native-tagged" mode in VLAN 9:
 303
 304              ovs-vsctl add-br br0
 305              ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged
 306
 307          In this situation, "native-untagged" mode will probably work
 308          equally well.  Refer to the documentation for the Port table
 309          in ovs-vswitchd.conf.db(5) for more information.
 310
 311 Q: Can I configure an IP address on a VLAN?
 312
 313 A: Yes.  Use an "internal port" configured as an access port.  For
 314    example, the following configures IP address 192.168.0.7 on VLAN 9.
 315    That is, OVS will forward packets from eth0 to 192.168.0.7 only if
 316    they have an 802.1Q header with VLAN 9.  Conversely, traffic
 317    forwarded from 192.168.0.7 to eth0 will be tagged with an 802.1Q
 318    header with VLAN 9:
 319
 320        ovs-vsctl add-br br0
 321        ovs-vsctl add-port br0 eth0
 322        ovs-vsctl add-port br0 vlan9 tag=9 -- set interface vlan9 type=internal
 323        ifconfig vlan9 192.168.0.7
 324
 325 Q: My OpenFlow controller doesn't see the VLANs that I expect.
 326
 327 A: The configuration for VLANs in the Open vSwitch database (e.g. via
 328    ovs-vsctl) only affects traffic that goes through Open vSwitch's
 329    implementation of the OpenFlow "normal switching" action.  By
 330    default, when Open vSwitch isn't connected to a controller and
 331    nothing has been manually configured in the flow table, all traffic
 332    goes through the "normal switching" action.  But, if you set up
 333    OpenFlow flows on your own, through a controller or using ovs-ofctl
 334    or through other means, then you have to implement VLAN handling
 335    yourself.
 336
 337    You can use "normal switching" as a component of your OpenFlow
 338    actions, e.g. by putting "normal" into the lists of actions on
 339    ovs-ofctl or by outputting to OFPP_NORMAL from an OpenFlow
 340    controller.  This will only be suitable for some situations,
 341    though.
 342
 343
 344 Controllers
 345 -----------
 346
 347 Q: I'm getting "error type 45250 code 0".  What's that?
 348
 349 A: This is a Open vSwitch extension to OpenFlow error codes.  Open
 350    vSwitch uses this extension when it must report an error to an
 351    OpenFlow controller but no standard OpenFlow error code is
 352    suitable.
 353
 354    Open vSwitch logs the errors that it sends to controllers, so the
 355    easiest thing to do is probably to look at the ovs-vswitchd log to
 356    find out what the error was.
 357
 358    If you want to dissect the extended error message yourself, the
 359    format is documented in include/openflow/nicira-ext.h in the Open
 360    vSwitch source distribution.  The extended error codes are
 361    documented in lib/ofp-errors.h.
 362
 363 Q1: Some of the traffic that I'd expect my OpenFlow controller to see
 364     doesn't actually appear through the OpenFlow connection, even
 365     though I know that it's going through.
 366 Q2: Some of the OpenFlow flows that my controller sets up don't seem
 367     to apply to certain traffic, especially traffic between OVS and
 368     the controller itself.
 369
 370 A: By default, Open vSwitch assumes that OpenFlow controllers are
 371    connected "in-band", that is, that the controllers are actually
 372    part of the network that is being controlled.  In in-band mode,
 373    Open vSwitch sets up special "hidden" flows to make sure that
 374    traffic can make it back and forth between OVS and the controllers.
 375    These hidden flows are higher priority than any flows that can be
 376    set up through OpenFlow, and they are not visible through normal
 377    OpenFlow flow table dumps.
 378
 379    Usually, the hidden flows are desirable and helpful, but
 380    occasionally they can cause unexpected behavior.  You can view the
 381    full OpenFlow flow table, including hidden flows, on bridge br0
 382    with the command:
 383
 384        ovs-appctl bridge/dump-flows br0
 385
 386    to help you debug.  The hidden flows are those with priorities
 387    greater than 65535 (the maximum priority that can be set with
 388    OpenFlow).
 389
 390    The DESIGN file at the top level of the Open vSwitch source
 391    distribution describes the in-band model in detail.
 392
 393    If your controllers are not actually in-band (e.g. they are on
 394    localhost via 127.0.0.1, or on a separate network), then you should
 395    configure your controllers in "out-of-band" mode.  If you have one
 396    controller on bridge br0, then you can configure out-of-band mode
 397    on it with:
 398
 399        ovs-vsctl set controller br0 connection-mode=out-of-band
 400
 401 Q: I configured all my controllers for out-of-band control mode but
 402    "ovs-appctl bridge/dump-flows" still shows some hidden flows.
 403
 404 A: You probably have a remote manager configured (e.g. with "ovs-vsctl
 405    set-manager").  By default, Open vSwitch assumes that managers need
 406    in-band rules set up on every bridge.  You can disable these rules
 407    on bridge br0 with:
 408
 409        ovs-vsctl set bridge br0 other-config:disable-in-band=true
 410
 411    This actually disables in-band control entirely for the bridge, as
 412    if all the bridge's controllers were configured for out-of-band
 413    control.
 414
 415 Q: My OpenFlow controller doesn't see the VLANs that I expect.
 416
 417 A: See answer under "VLANs", above.
 418
 419 Contact
 420 -------
 421
 422 bugs@openvswitch.org
 423 http://openvswitch.org/