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