1 Frequently Asked Questions
2 ==========================
4 Open vSwitch <http://openvswitch.org>
9 ### Q: What is Open vSwitch?
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
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.
27 ### Q: What virtualization platforms can use Open vSwitch?
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
37 ### Q: How can I try Open vSwitch?
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.
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
50 ### Q: Does Open vSwitch only work on Linux?
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.
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.
62 ### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC?
64 A: The [PORTING.md] document describes how one would go about
65 porting Open vSwitch to a new operating system or hardware platform.
67 ### Q: Why would I use Open vSwitch instead of the Linux bridge?
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.
75 ### Q: How is Open vSwitch related to distributed virtual switches like the VMware vNetwork distributed switch or the Cisco Nexus 1000V?
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.
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.
94 ### Q: Why doesn't Open vSwitch support distribution?
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.
104 ### Q: How can I contribute to the Open vSwitch Community?
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:
111 http://openvswitch.org/mlists/
113 ### Q: Why can I no longer connect to my OpenFlow controller or OVSDB
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.
126 ### Q: What does it mean for an Open vSwitch release to be LTS (long-term support)?
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
136 ### Q: What Linux kernel versions does each Open vSwitch release work with?
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.
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
161 Open vSwitch userspace should also work with the Linux kernel module
162 built into Linux 3.3 and later.
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
168 ### Q: I get an error like this when I configure Open vSwitch:
170 configure: error: Linux kernel in <dir> is version <x>, but
171 version newer than <y> is not supported (please refer to the
176 A: You have the following options:
178 - Use the Linux kernel module supplied with the kernel that you are
179 using. (See also the following FAQ.)
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
186 - The Open vSwitch "master" branch may support the kernel that you
187 are using, so consider building the kernel module from "master".
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.
194 ### Q: What features are not available in the Open vSwitch kernel datapath that ships as part of the upstream Linux kernel?
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.
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
208 ### Q: Why do tunnels not work when using a kernel module other than the one packaged with Open vSwitch?
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:
215 | Protocol | Linux Kernel
216 |:--------:|:-------------:
220 | LISP | <not upstream>
221 | STT | <not upstream>
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.
230 ### Q: Why are UDP tunnel checksums not computed for VXLAN or Geneve?
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.
238 ### Q: What features are not available when using the userspace datapath?
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.
245 ### Q: What Linux kernel versions does IPFIX flow monitoring work with?
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
251 ### Q: Should userspace or kernel be upgraded first to minimize downtime?
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.
259 ### Q: What happened to the bridge compatibility feature?
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.
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
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.
282 ### Q: I thought Open vSwitch was a virtual Ethernet switch, but the documentation keeps talking about bridges. What's a bridge?
284 A: In networking, the terms "bridge" and "switch" are synonyms. Open
285 vSwitch implements an Ethernet switch, which means that it is also
288 ### Q: What's a VLAN?
290 A: See the "VLAN" section below.
296 ### Q: How do I configure a port as an access port?
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:
303 ovs-vsctl add-port br0 eth0
304 ovs-vsctl add-port br0 tap0 tag=9
306 If you want to configure an already added port as an access port,
307 use "ovs-vsctl set", e.g.:
309 ovs-vsctl set port tap0 tag=9
311 ### Q: How do I configure a port as a SPAN port, that is, enable mirroring of all traffic to that port?
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:
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
325 To later disable mirroring, run:
327 ovs-vsctl clear bridge br0 mirrors
329 ### Q: Does Open vSwitch support configuring a port in promiscuous mode?
331 A: Yes. How you configure it depends on what you mean by "promiscuous
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.
346 This form of promiscuous mode is configured in the guest OS of
347 the VMs on your bridge, e.g. with "ifconfig".
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.
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?"
363 ### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN?
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
373 ovs-vsctl add-port br0 eth0
374 ovs-vsctl add-port br0 tap0 tag=10
376 -- --id=@m create mirror name=m0 select-all=true select-vlan=10 \
378 -- set bridge br0 mirrors=@m
380 To later disable mirroring, run:
382 ovs-vsctl clear bridge br0 mirrors
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.
389 ### Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
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.
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
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.
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.
413 ### Q: How do I configure mirroring of all traffic to a GRE tunnel?
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:
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
429 To later disable mirroring and destroy the GRE tunnel:
431 ovs-vsctl clear bridge br0 mirrors
432 ovs-vcstl del-port br0 gre0
434 ### Q: Does Open vSwitch support ERSPAN?
436 A: No. ERSPAN is an undocumented proprietary protocol. As an
437 alternative, Open vSwitch supports mirroring to a GRE tunnel (see
440 ### Q: How do I connect two bridges?
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.
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.
452 ovs-vsctl add-port br0 eth0
453 ovs-vsctl add-port br0 tap0
455 ovs-vsctl add-port br1 tap1
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
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).
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
477 ### Q: How do I configure a bridge without an OpenFlow local port? (Local port in the sense of OFPP_LOCAL)
479 A: Open vSwitch does not support such a configuration.
480 Bridges always have their local ports.
483 Implementation Details
484 ----------------------
486 ### Q: I hear OVS has a couple of kinds of flows. Can you tell me about them?
488 A: Open vSwitch uses different kinds of flows for different purposes:
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
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
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.
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.
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.
518 ### Q: Why are there so many different ways to dump flows?
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
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.)
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.
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.
540 - `ovs-appctl dpif/dump-flows <br>`, new in Open vSwitch 1.10,
541 dumps datapath flows for only the specified bridge, regardless
544 ### Q: How does multicast snooping works with VLANs?
546 A: Open vSwitch maintains snooping tables for each VLAN.
552 ### Q: I just upgraded and I see a performance drop. Why?
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
562 Updating the OVS userspace components to the latest released
563 version should fix the performance degradation.
565 To get the best possible performance and functionality, it is
566 recommended to pair the same versions of the kernel module and OVS
570 Configuration Problems
571 ----------------------
573 ### Q: I created a bridge and added my Ethernet port to it, using commands
577 ovs-vsctl add-port br0 eth0
579 and as soon as I ran the "add-port" command I lost all connectivity
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.
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
592 ifconfig eth0 0.0.0.0
593 ifconfig br0 192.168.128.5
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.
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").
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.
614 By the way, this issue is not specific to physical Ethernet
615 devices. It applies to all network devices except Open vSwitch
618 ### Q: I created a bridge and added a couple of Ethernet ports to it,
619 ### using commands like these:
622 ovs-vsctl add-port br0 eth0
623 ovs-vsctl add-port br0 eth1
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.
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
638 The solution depends on what you are trying to do:
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:
646 ovs-vsctl add-bond br0 bond0 eth0 eth1
648 Bonds have tons of configuration options. Please read the
649 documentation on the Port table in ovs-vswitchd.conf.db(5)
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:
658 ovs-vsctl add-port br0 eth0
661 ovs-vsctl add-port br1 eth1
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,
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
676 ovs-vsctl set bridge br0 stp_enable=true
677 ovs-vsctl add-port br0 eth0
678 ovs-vsctl add-port br0 eth1
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
685 ### Q: I can't seem to use Open vSwitch in a wireless network.
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.
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.
696 ### Q: I can't seem to add my PPP interface to an Open vSwitch bridge.
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.
702 ### Q: Is there any documentation on the database tables and fields?
704 A: Yes. ovs-vswitchd.conf.db(5) is a comprehensive reference.
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?
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.
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?
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.
725 ### Q: Open vSwitch does not seem to obey my packet filter rules.
727 A: It depends on mechanisms and configurations you want to use.
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.)
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.
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
746 For simple filtering rules, it might be possible to achieve similar
747 results by installing appropriate OpenFlow flows instead.
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.
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:
759 ovs-vsctl del-port br0 p1 -- \
761 set interface p1 type=internal
763 A: It's an expected behaviour.
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
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:
779 ovs-vsctl del-port br0 p1
780 ovs-vsctl add-port br0 p1 -- \
781 set interface p1 type=internal
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
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.
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:
798 cmds=; for i in {1..5000}; do cmds+=" -- add-port br0 p$i"; done
801 takes seconds, not minutes or hours, in the OVS sandbox environment.
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
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).
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".)
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
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.
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
837 Quality of Service (QoS)
838 ------------------------
840 ### Q: How do I configure Quality of Service (QoS)?
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:
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
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.
867 We use OpenFlow to direct packets from vif1.0 and vif2.0 to the
868 queues reserved for them:
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
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.)
882 Now traffic going from vif1.0 or vif2.0 to eth0 should be
885 By the way, if you delete the bridge created by the above commands,
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:
895 ovs-vsctl -- --all destroy QoS -- --all destroy Queue
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
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
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.
911 Refer to the previous question for an example.
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?
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.)
926 ### Q: I configured QoS, correctly, but my measurements show that it isn't
927 working as well as I expect.
929 A: With the Linux kernel, the Open vSwitch implementation of QoS has
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.
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
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.
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).
958 ### Q: Does Open vSwitch support OpenFlow meters?
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
969 ### Q: What's a VLAN?
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.
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.
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
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.
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.
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.)
1023 ### Q: VLANs don't work.
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:
1029 - Upgrade to Linux 3.3 or later.
1031 - Build and install a fixed version of the particular driver
1032 that is causing trouble, if one is available.
1034 - Use a NIC whose driver does not have VLAN problems.
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:
1040 ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true
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.
1047 VLAN splinters increase memory use and reduce performance, so
1048 use them only if needed.
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.
1055 (This is a nontrivial exercise, so this option is included
1056 only for completeness.)
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.
1064 ### Q: VLANs still don't work. I've tested the driver so I know that it's OK.
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.
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
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.
1080 If this is the case, you have two choices:
1082 - Change the physical switch port configuration to tag packets
1083 it forwards to OVS with the native VLAN instead of forwarding
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:
1090 ovs-vsctl add-br br0
1091 ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged
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.
1097 ### Q: I added a pair of VMs on different VLANs, like this:
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
1104 but the VMs can't access each other, the external network, or the
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.
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).
1116 ### Q: I added a pair of VMs on the same VLAN, like this:
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
1123 The VMs can access each other, but not the external network or the
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.
1131 ### Q: Can I configure an IP address on a VLAN?
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
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
1145 See also the following question.
1147 ### Q: I configured one IP address on VLAN 0 and another on VLAN 9, like
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
1156 but other hosts that are only on VLAN 0 can reach the IP address
1157 configured on VLAN 9. What's going on?
1159 A: RFC 1122 section 3.3.4.2 "Multihoming Requirements" describes two
1160 approaches to IP address handling in Internet hosts:
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.
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.
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
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.
1187 BSD uses the strong ES model.
1189 ### Q: My OpenFlow controller doesn't see the VLANs that I expect.
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
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.:
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.
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.
1215 ### Q: I configured ports on a bridge as access ports with different VLAN
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
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
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.
1233 ### Q: How MAC learning works with VLANs?
1235 A: Open vSwitch implements Independent VLAN Learning (IVL) for
1236 OFPP_NORMAL action. I.e. it logically has separate learning tables
1243 ### Q: What's a VXLAN?
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
1251 http://tools.ietf.org/html/rfc7348
1253 ### Q: How much of the VXLAN protocol does Open vSwitch currently support?
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
1261 ### Q: What destination UDP port does the VXLAN implementation in Open vSwitch
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
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
1275 Using OpenFlow (Manually or Via Controller)
1276 -------------------------------------------
1278 ### Q: What versions of OpenFlow does Open vSwitch support?
1280 A: The following table lists the versions of OpenFlow supported by
1281 each version of Open vSwitch:
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 [*] [*]
1293 [*] Supported, with one or more missing features.
1294 [%] Experimental, unsafe implementation.
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:
1303 - To enable OpenFlow 1.0, 1.1, 1.2, and 1.3 on bridge br0:
1305 ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13
1307 - To enable OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 on bridge br0:
1309 ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15
1311 - To enable only OpenFlow 1.0 on bridge br0:
1313 ovs-vsctl set bridge br0 protocols=OpenFlow10
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:
1319 ovs-ofctl -O OpenFlow13 dump-flows br0
1321 (Open vSwitch 2.2 had an experimental implementation of OpenFlow
1322 1.4 that could cause crashes. We don't recommend enabling it.)
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.
1330 ### Q: Does Open vSwitch support MPLS?
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.
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
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.
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
1355 ### Q: I'm getting "error type 45250 code 0". What's that?
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
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.
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.
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.
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.
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
1392 ovs-appctl bridge/dump-flows br0
1394 to help you debug. The hidden flows are those with priorities
1395 greater than 65535 (the maximum priority that can be set with
1398 The DESIGN file at the top level of the Open vSwitch source
1399 distribution describes the in-band model in detail.
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
1407 ovs-vsctl set controller br0 connection-mode=out-of-band
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.
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
1417 ovs-vsctl set bridge br0 other-config:disable-in-band=true
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
1423 ### Q: My OpenFlow controller doesn't see the VLANs that I expect.
1425 A: See answer under "VLANs", above.
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:
1430 ofp_util|INFO|normalization changed ofp_match, details:
1431 ofp_util|INFO| pre: nw_dst=192.168.0.1
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
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.
1443 In this case, the L3 protocol could be IP or ARP. A correct
1444 command for each possibility is, respectively:
1446 ovs-ofctl add-flow br0 ip,nw_dst=192.168.0.1,actions=drop
1450 ovs-ofctl add-flow br0 arp,nw_dst=192.168.0.1,actions=drop
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".
1458 ### Q: How can I figure out the OpenFlow port number for a given port?
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.
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:
1470 ovs-vsctl get Interface eth0 ofport
1472 You can print the entire mapping with:
1474 ovs-vsctl -- --columns=name,ofport list Interface
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.
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
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.
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.
1493 ### Q: It looks like each of the interfaces in my bonded port shows up
1494 as an individual OpenFlow port. Is that right?
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:
1500 - Sending a packet to the OFPP_NORMAL port. (When an OpenFlow
1501 controller is not configured, this happens implicitly to
1504 - Mirrors configured for output to a bonded port.
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.
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
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
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.)
1527 Tools available for tracing include the following:
1529 - "tcpdump" and "wireshark" for observing hops across network
1530 devices, such as Open vSwitch internal devices and physical
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.
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.
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"
1550 - SPAN, RSPAN, and ERSPAN features of physical switches, to
1551 observe what goes on at these physical hops.
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
1557 1. "tcpdump" the "eth" interface through which an ARP egresses
1558 a VM, from inside the VM.
1560 2. "tcpdump" the "vif" or "tap" interface through which the ARP
1561 ingresses the host machine.
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
1571 4. "tcpdump" the "eth" interface through which the ARP egresses
1572 the physical machine.
1574 5. "tcpdump" the "eth" interface through which the ARP
1575 ingresses the physical machine, at the remote host that
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.
1583 7. "tcpdump" the "vif" or "tap" interface to which the ARP is
1586 8. "tcpdump" the "eth" interface through which the ARP
1587 ingresses a VM, from inside the VM.
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
1593 ### Q: How do I make a flow drop packets?
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:
1601 ovs-ofctl add-flow br0 priority=65535,actions=
1603 would cause every packet entering switch br0 to be dropped.
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:
1609 ovs-ofctl add-flow br0 priority=65535,actions=drop
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.
1614 ### Q: I added a flow to send packets out the ingress port, like this:
1616 ovs-ofctl add-flow br0 in_port=2,actions=2
1618 but OVS drops the packets instead.
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).
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.:
1630 ovs-ofctl add-flow br0 in_port=2,actions=in_port
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:
1637 ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
1641 ovs-ofctl add-flow br0 actions=all,in_port
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:
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
1656 If the input port is important, then one may save and restore it on
1659 ovs-ofctl add-flow br0 actions=push:NXM_OF_IN_PORT[],\
1660 load:0->NXM_OF_IN_PORT[],\
1662 pop:NXM_OF_IN_PORT[]
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:
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
1672 But it doesn't work--I don't get any connectivity when I do this.
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:
1679 priority=5,in_port=1,arp,actions=2
1680 priority=5,in_port=2,arp,actions=1
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:
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
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
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
1698 ### Q: My bridge disconnects from my controller on add-port/del-port.
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.
1705 To avoid the behaviour, you can configure datapath-id manually.
1707 ovs-vsctl set bridge br0 other-config:datapath-id=0123456789abcdef
1709 ### Q: My controller is getting errors about "buffers". What's going on?
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.
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
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.
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.
1746 ovs-vswitchd(8) describes some details of Open vSwitch packet
1747 buffering that the OpenFlow specification requires implementations
1754 ### Q: How do I implement a new OpenFlow message?
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.)
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.
1766 ### Q: How do I add support for a new field or header?
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
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
1790 ### Q: How do I add support for a new OpenFlow action?
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
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.
1807 bugs@openvswitch.org
1808 http://openvswitch.org/
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