util: New function follow_symlinks().
[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 environments.  A
13    vswitch forwards traffic between different VMs on the same physical host
14    and also forwards traffic between VMs and the physical network.  Open
15    vSwitch supports standard management interfaces (e.g. sFlow, NetFlow,
16    RSPAN, CLI), and is open to programmatic extension and control using
17    OpenFlow and the OVSDB management protocol.
18
19    Open vSwitch as designed to be compatible with modern switching
20    chipsets.  This means that it can be ported to existing high-fanout
21    switches allowing the same flexible control of the physical
22    infrastructure as the virtual infrastructure.  It also means that
23    Open vSwitch will be able to take advantage of on-NIC switching
24    chipsets as their functionality matures.
25
26 Q: What virtualization platforms can use Open vSwitch?
27
28 A: Open vSwitch can currently run on any Linux-based virtualization
29    platform (kernel 2.6.18 and newer), including: KVM, VirtualBox, Xen,
30    Xen Cloud Platform, XenServer. As of Linux 3.3 it is part of the
31    mainline kernel.  The bulk of the code is written in platform-
32    independent C and is easily ported to other environments.  We welcome
33    inquires about integrating Open vSwitch with other virtualization
34    platforms.
35
36 Q: How can I try Open vSwitch?
37
38 A: The Open vSwitch source code can be built on a Linux system.  You can
39    build and experiment with Open vSwitch on any Linux machine.
40    Packages for various Linux distributions are available on many
41    platforms, including: Debian, Ubuntu, Fedora.
42
43    You may also download and run a virtualization platform that already
44    has Open vSwitch integrated.  For example, download a recent ISO for
45    XenServer or Xen Cloud Platform.  Be aware that the version
46    integrated with a particular platform may not be the most recent Open
47    vSwitch release.
48
49 Q: Does Open vSwitch only work on Linux?
50
51 A: No, Open vSwitch has been ported to a number of different operating
52    systems and hardware platforms.  Most of the development work occurs
53    on Linux, but the code should be portable to any POSIX system.  We've
54    seen Open vSwitch ported to a number of different platforms,
55    including FreeBSD, Windows, and even non-POSIX embedded systems.
56
57    By definition, the Open vSwitch Linux kernel module only works on
58    Linux and will provide the highest performance.  However, a userspace
59    datapath is available that should be very portable.
60
61 Q: What's involved with porting Open vSwitch to a new platform or
62    switching ASIC?
63
64 A: The PORTING document describes how one would go about porting Open
65    vSwitch to a new operating system or hardware platform.
66
67 Q: Why would I use Open vSwitch instead of the Linux bridge?
68
69 A: Open vSwitch is specially designed to make it easier to manage VM
70    network configuration and monitor state spread across many physical
71    hosts in dynamic virtualized environments.  Please see WHY-OVS for a
72    more detailed description of how Open vSwitch relates to the Linux
73    Bridge.
74
75 Q: How is Open vSwitch related to distributed virtual switches like the
76    VMware vNetwork distributed switch or the Cisco Nexus 1000V?
77
78 A: Distributed vswitch applications (e.g., VMware vNetwork distributed
79    switch, Cisco Nexus 1000V) provide a centralized way to configure and
80    monitor the network state of VMs that are spread across many physical
81    hosts.  Open vSwitch is not a distributed vswitch itself, rather it
82    runs on each physical host and supports remote management in a way
83    that makes it easier for developers of virtualization/cloud
84    management platforms to offer distributed vswitch capabilities.
85
86    To aid in distribution, Open vSwitch provides two open protocols that
87    are specially designed for remote management in virtualized network
88    environments: OpenFlow, which exposes flow-based forwarding state,
89    and the OVSDB management protocol, which exposes switch port state.
90    In addition to the switch implementation itself, Open vSwitch
91    includes tools (ovs-controller, ovs-ofctl, ovs-vsctl) that developers
92    can script and extend to provide distributed vswitch capabilities
93    that are closely integrated with their virtualization management
94    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
117 Releases
118 --------
119
120 Q: What does it mean for an Open vSwitch release to be LTS (long-term
121    support)?
122
123 A: All official releases have been through a comprehensive testing
124    process and are suitable for production use.  Planned releases will
125    occur several times a year.  If a significant bug is identified in an
126    LTS release, we will provide an updated release that includes the
127    fix.  Releases that are not LTS may not be fixed and may just be
128    supplanted by the next major release.  The current LTS release is
129    1.4.x.
130
131 Q: What features are not available in the Open vSwitch kernel datapath
132    that ships as part of the upstream Linux kernel?
133
134 A: The kernel module in upstream Linux 3.3 and later does not include
135    the following features:
136
137        - Bridge compatibility, that is, support for the ovs-brcompatd
138          daemon that (if you enable it) lets "brctl" and other Linux
139          bridge tools transparently work with Open vSwitch instead.
140
141          We do not expect bridge compatibility to ever be available in
142          upstream Linux.  If you need bridge compatibility, use the
143          kernel module from the Open vSwitch distribution instead of the
144          upstream Linux kernel module.
145
146        - Tunnel virtual ports, that is, interfaces with type "gre",
147          "ipsec_gre", "capwap".  It is possible to create tunnels in
148          Linux and attach them to Open vSwitch as system devices.
149          However, they cannot be dynamically created through the OVSDB
150          protocol or set the tunnel ids as a flow action.
151
152          Work is in progress in adding these features to the upstream
153          Linux version of the Open vSwitch kernel module.  For now, if
154          you need these features, use the kernel module from the Open
155          vSwitch distribution instead of the upstream Linux kernel
156          module.
157
158        - Patch virtual ports, that is, interfaces with type "patch".
159          You can use Linux "veth" devices as a substitute.
160
161          We don't have any plans to add patch ports upstream.
162
163 Q: What features are not available when using the userspace datapath?
164
165 A: Tunnel and patch virtual ports are not supported, as described in the
166    previous answer.  It is also not possible to use queue-related
167    actions.  On Linux kernels before 2.6.39, maximum-sized VLAN packets
168    may not be transmitted.
169
170
171 Configuration Problems
172 ----------------------
173
174 Q: I created a bridge and added my Ethernet port to it, using commands
175    like these:
176
177        ovs-vsctl add-br br0
178        ovs-vsctl add-port br0 eth0
179
180    and as soon as I ran the "add-port" command I lost all connectivity
181    through eth0.  Help!
182
183 A: A physical Ethernet device that is part of an Open vSwitch bridge
184    should not have an IP address.  If one does, then that IP address
185    will not be fully functional.
186
187    You can restore functionality by moving the IP address to an Open
188    vSwitch "internal" device, such as the network device named after
189    the bridge itself.  For example, assuming that eth0's IP address is
190    192.168.128.5, you could run the commands below to fix up the
191    situation:
192
193        ifconfig eth0 0.0.0.0
194        ifconfig br0 192.168.128.5
195
196    (If your only connection to the machine running OVS is through the
197    IP address in question, then you would want to run all of these
198    commands on a single command line, or put them into a script.)  If
199    there were any additional routes assigned to eth0, then you would
200    also want to use commands to adjust these routes to go through br0.
201
202    If you use DHCP to obtain an IP address, then you should kill the
203    DHCP client that was listening on the physical Ethernet interface
204    (e.g. eth0) and start one listening on the internal interface
205    (e.g. br0).  You might still need to manually clear the IP address
206    from the physical interface (e.g. with "ifconfig eth0 0.0.0.0").
207
208    There is no compelling reason why Open vSwitch must work this way.
209    However, this is the way that the Linux kernel bridge module has
210    always worked, so it's a model that those accustomed to Linux
211    bridging are already used to.  Also, the model that most people
212    expect is not implementable without kernel changes on all the
213    versions of Linux that Open vSwitch supports.
214
215    By the way, this issue is not specific to physical Ethernet
216    devices.  It applies to all network devices except Open vswitch
217    "internal" devices.
218
219 Q: I created a bridge and added a couple of Ethernet ports to it,
220    using commands like these:
221
222        ovs-vsctl add-br br0
223        ovs-vsctl add-port br0 eth0
224        ovs-vsctl add-port br0 eth1
225
226    and now my network seems to have melted: connectivity is unreliable
227    (even connectivity that doesn't go through Open vSwitch), all the
228    LEDs on my physical switches are blinking, wireshark shows
229    duplicated packets, and CPU usage is very high.
230
231 A: More than likely, you've looped your network.  Probably, eth0 and
232    eth1 are connected to the same physical Ethernet switch.  This
233    yields a scenario where OVS receives a broadcast packet on eth0 and
234    sends it out on eth1, then the physical switch connected to eth1
235    sends the packet back on eth0, and so on forever.  More complicated
236    scenarios, involving a loop through multiple switches, are possible
237    too.
238
239    The solution depends on what you are trying to do:
240
241        - If you added eth0 and eth1 to get higher bandwidth or higher
242          reliability between OVS and your physical Ethernet switch,
243          use a bond.  The following commands create br0 and then add
244          eth0 and eth1 as a bond:
245
246              ovs-vsctl add-br br0
247              ovs-vsctl add-bond br0 bond0 eth0 eth1
248
249          Bonds have tons of configuration options.  Please read the
250          documentation on the Port table in ovs-vswitchd.conf.db(5)
251          for all the details.
252
253        - Perhaps you don't actually need eth0 and eth1 to be on the
254          same bridge.  For example, if you simply want to be able to
255          connect each of them to virtual machines, then you can put
256          each of them on a bridge of its own:
257
258              ovs-vsctl add-br br0
259              ovs-vsctl add-port br0 eth0
260
261              ovs-vsctl add-br br1
262              ovs-vsctl add-port br1 eth1
263
264          and then connect VMs to br0 and br1.  (A potential
265          disadvantage is that traffic cannot directly pass between br0
266          and br1.  Instead, it will go out eth0 and come back in eth1,
267          or vice versa.)
268
269        - If you have a redundant or complex network topology and you
270          want to prevent loops, turn on spanning tree protocol (STP).
271          The following commands create br0, enable STP, and add eth0
272          and eth1 to the bridge.  The order is important because you
273          don't want have to have a loop in your network even
274          transiently:
275
276              ovs-vsctl add-br br0
277              ovs-vsctl set bridge br0 stp_enable=true
278              ovs-vsctl add-port br0 eth0
279              ovs-vsctl add-port br0 eth1
280
281          The Open vSwitch implementation of STP is not well tested.
282          Please report any bugs you observe, but if you'd rather avoid
283          acting as a beta tester then another option might be your
284          best shot.
285
286 Q: I can't seem to use Open vSwitch in a wireless network.
287
288 A: Wireless base stations generally only allow packets with the source
289    MAC address of NIC that completed the initial handshake.
290    Therefore, without MAC rewriting, only a single device can
291    communicate over a single wireless link.
292
293    This isn't specific to Open vSwitch, it's enforced by the access
294    point, so the same problems will show up with the Linux bridge or
295    any other way to do bridging.
296
297 Q: Is there any documentation on the database tables and fields?
298
299 A: Yes.  ovs-vswitchd.conf.db(5) is a comprehensive reference.
300
301
302 VLANs
303 -----
304
305 Q: VLANs don't work.
306
307 A: Many drivers in Linux kernels before version 3.3 had VLAN-related
308    bugs.  If you are having problems with VLANs that you suspect to be
309    driver related, then you have several options:
310
311        - Upgrade to Linux 3.3 or later.
312
313        - Build and install a fixed version of the particular driver
314          that is causing trouble, if one is available.
315
316        - Use a NIC whose driver does not have VLAN problems.
317
318        - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later
319          that works around bugs in kernel drivers.  To enable VLAN
320          splinters on interface eth0, use the command:
321
322            ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true
323
324          For VLAN splinters to be effective, Open vSwitch must know
325          which VLANs are in use.  See the "VLAN splinters" section in
326          the Interface table in ovs-vswitchd.conf.db(5) for details on
327          how Open vSwitch infers in-use VLANs.
328
329          VLAN splinters increase memory use and reduce performance, so
330          use them only if needed.
331
332        - Apply the "vlan workaround" patch from the XenServer kernel
333          patch queue, build Open vSwitch against this patched kernel,
334          and then use ovs-vlan-bug-workaround(8) to enable the VLAN
335          workaround for each interface whose driver is buggy.
336
337          (This is a nontrivial exercise, so this option is included
338          only for completeness.)
339
340    It is not always easy to tell whether a Linux kernel driver has
341    buggy VLAN support.  The ovs-vlan-test(8) and ovs-test(8) utilities
342    can help you test.  See their manpages for details.  Of the two
343    utilities, ovs-test(8) is newer and more thorough, but
344    ovs-vlan-test(8) may be easier to use.
345
346 Q: VLANs still don't work.  I've tested the driver so I know that it's OK.
347
348 A: Do you have VLANs enabled on the physical switch that OVS is
349    attached to?  Make sure that the port is configured to trunk the
350    VLAN or VLANs that you are using with OVS.
351
352 Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch
353    and to its destination host, but OVS seems to drop incoming return
354    traffic.
355
356 A: It's possible that you have the VLAN configured on your physical
357    switch as the "native" VLAN.  In this mode, the switch treats
358    incoming packets either tagged with the native VLAN or untagged as
359    part of the native VLAN.  It may also send outgoing packets in the
360    native VLAN without a VLAN tag.
361
362    If this is the case, you have two choices:
363
364        - Change the physical switch port configuration to tag packets
365          it forwards to OVS with the native VLAN instead of forwarding
366          them untagged.
367
368        - Change the OVS configuration for the physical port to a
369          native VLAN mode.  For example, the following sets up a
370          bridge with port eth0 in "native-tagged" mode in VLAN 9:
371
372              ovs-vsctl add-br br0
373              ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged
374
375          In this situation, "native-untagged" mode will probably work
376          equally well.  Refer to the documentation for the Port table
377          in ovs-vswitchd.conf.db(5) for more information.
378
379 Q: Can I configure an IP address on a VLAN?
380
381 A: Yes.  Use an "internal port" configured as an access port.  For
382    example, the following configures IP address 192.168.0.7 on VLAN 9.
383    That is, OVS will forward packets from eth0 to 192.168.0.7 only if
384    they have an 802.1Q header with VLAN 9.  Conversely, traffic
385    forwarded from 192.168.0.7 to eth0 will be tagged with an 802.1Q
386    header with VLAN 9:
387
388        ovs-vsctl add-br br0
389        ovs-vsctl add-port br0 eth0
390        ovs-vsctl add-port br0 vlan9 tag=9 -- set interface vlan9 type=internal
391        ifconfig vlan9 192.168.0.7
392
393 Q: My OpenFlow controller doesn't see the VLANs that I expect.
394
395 A: The configuration for VLANs in the Open vSwitch database (e.g. via
396    ovs-vsctl) only affects traffic that goes through Open vSwitch's
397    implementation of the OpenFlow "normal switching" action.  By
398    default, when Open vSwitch isn't connected to a controller and
399    nothing has been manually configured in the flow table, all traffic
400    goes through the "normal switching" action.  But, if you set up
401    OpenFlow flows on your own, through a controller or using ovs-ofctl
402    or through other means, then you have to implement VLAN handling
403    yourself.
404
405    You can use "normal switching" as a component of your OpenFlow
406    actions, e.g. by putting "normal" into the lists of actions on
407    ovs-ofctl or by outputting to OFPP_NORMAL from an OpenFlow
408    controller.  This will only be suitable for some situations,
409    though.
410
411 Q: I configured ports on a bridge as access ports with different VLAN
412    tags, like this:
413
414        ovs-vsctl add-br br0
415        ovs-vsctl set-controller br0 tcp:192.168.0.10:6633
416        ovs-vsctl add-port br0 eth0
417        ovs-vsctl add-port br0 tap0 tag=9
418        ovs-vsctl add-port br0 tap1 tag=10
419
420    but the VMs running behind tap0 and tap1 can still communicate,
421    that is, they are not isolated from each other even though they are
422    on different VLANs.
423
424 A: Do you have a controller configured on br0 (as the commands above
425    do)?  If so, then this is a variant on the previous question, "My
426    OpenFlow controller doesn't see the VLANs that I expect," and you
427    can refer to the answer there for more information.
428
429
430 Controllers
431 -----------
432
433 Q: What versions of OpenFlow does Open vSwitch support?
434
435 A: Open vSwitch supports OpenFlow 1.0.  It also includes a number of
436    extensions that bring many of the features from later versions of
437    OpenFlow.  Work is underway to provide support for later versions and
438    can be tracked here:
439
440        http://openvswitch.org/development/openflow-1-x-plan/
441
442 Q: I'm getting "error type 45250 code 0".  What's that?
443
444 A: This is a Open vSwitch extension to OpenFlow error codes.  Open
445    vSwitch uses this extension when it must report an error to an
446    OpenFlow controller but no standard OpenFlow error code is
447    suitable.
448
449    Open vSwitch logs the errors that it sends to controllers, so the
450    easiest thing to do is probably to look at the ovs-vswitchd log to
451    find out what the error was.
452
453    If you want to dissect the extended error message yourself, the
454    format is documented in include/openflow/nicira-ext.h in the Open
455    vSwitch source distribution.  The extended error codes are
456    documented in lib/ofp-errors.h.
457
458 Q1: Some of the traffic that I'd expect my OpenFlow controller to see
459     doesn't actually appear through the OpenFlow connection, even
460     though I know that it's going through.
461 Q2: Some of the OpenFlow flows that my controller sets up don't seem
462     to apply to certain traffic, especially traffic between OVS and
463     the controller itself.
464
465 A: By default, Open vSwitch assumes that OpenFlow controllers are
466    connected "in-band", that is, that the controllers are actually
467    part of the network that is being controlled.  In in-band mode,
468    Open vSwitch sets up special "hidden" flows to make sure that
469    traffic can make it back and forth between OVS and the controllers.
470    These hidden flows are higher priority than any flows that can be
471    set up through OpenFlow, and they are not visible through normal
472    OpenFlow flow table dumps.
473
474    Usually, the hidden flows are desirable and helpful, but
475    occasionally they can cause unexpected behavior.  You can view the
476    full OpenFlow flow table, including hidden flows, on bridge br0
477    with the command:
478
479        ovs-appctl bridge/dump-flows br0
480
481    to help you debug.  The hidden flows are those with priorities
482    greater than 65535 (the maximum priority that can be set with
483    OpenFlow).
484
485    The DESIGN file at the top level of the Open vSwitch source
486    distribution describes the in-band model in detail.
487
488    If your controllers are not actually in-band (e.g. they are on
489    localhost via 127.0.0.1, or on a separate network), then you should
490    configure your controllers in "out-of-band" mode.  If you have one
491    controller on bridge br0, then you can configure out-of-band mode
492    on it with:
493
494        ovs-vsctl set controller br0 connection-mode=out-of-band
495
496 Q: I configured all my controllers for out-of-band control mode but
497    "ovs-appctl bridge/dump-flows" still shows some hidden flows.
498
499 A: You probably have a remote manager configured (e.g. with "ovs-vsctl
500    set-manager").  By default, Open vSwitch assumes that managers need
501    in-band rules set up on every bridge.  You can disable these rules
502    on bridge br0 with:
503
504        ovs-vsctl set bridge br0 other-config:disable-in-band=true
505
506    This actually disables in-band control entirely for the bridge, as
507    if all the bridge's controllers were configured for out-of-band
508    control.
509
510 Q: My OpenFlow controller doesn't see the VLANs that I expect.
511
512 A: See answer under "VLANs", above.
513
514 Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop"
515    but I got a funny message like this:
516
517        ofp_util|INFO|normalization changed ofp_match, details:
518        ofp_util|INFO| pre: nw_dst=192.168.0.1
519        ofp_util|INFO|post:
520
521    and when I ran "ovs-ofctl dump-flows br0" I saw that my nw_dst
522    match had disappeared, so that the flow ends up matching every
523    packet.
524
525 A: The term "normalization" in the log message means that a flow
526    cannot match on an L3 field without saying what L3 protocol is in
527    use.  The "ovs-ofctl" command above didn't specify an L3 protocol,
528    so the L3 field match was dropped.
529
530    In this case, the L3 protocol could be IP or ARP.  A correct
531    command for each possibility is, respectively:
532
533        ovs-ofctl add-flow br0 ip,nw_dst=192.168.0.1,actions=drop
534
535    and 
536
537        ovs-ofctl add-flow br0 arp,nw_dst=192.168.0.1,actions=drop
538
539    Similarly, a flow cannot match on an L4 field without saying what
540    L4 protocol is in use.  For example, the flow match "tp_src=1234"
541    is, by itself, meaningless and will be ignored.  Instead, to match
542    TCP source port 1234, write "tcp,tp_src=1234", or to match UDP
543    source port 1234, write "udp,tp_src=1234".
544
545 Q: How can I figure out the OpenFlow port number for a given port?
546
547 A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to
548    respond with an OFPT_FEATURES_REPLY that, among other information,
549    includes a mapping between OpenFlow port names and numbers.  From a
550    command prompt, "ovs-ofctl show br0" makes such a request and
551    prints the response for switch br0.
552
553    The Interface table in the Open vSwitch database also maps OpenFlow
554    port names to numbers.  To print the OpenFlow port number
555    associated with interface eth0, run:
556
557        ovs-vsctl get Interface eth0 ofport
558
559    You can print the entire mapping with:
560
561        ovs-vsctl -- --columns=name,ofport list Interface
562
563    but the output mixes together interfaces from all bridges in the
564    database, so it may be confusing if more than one bridge exists.
565
566    In the Open vSwitch database, ofport value -1 means that the
567    interface could not be created due to an error.  (The Open vSwitch
568    log should indicate the reason.)  ofport value [] (the empty set)
569    means that the interface hasn't been created yet.  The latter is
570    normally an intermittent condition (unless ovs-vswitchd is not
571    running).
572
573 Contact 
574 -------
575
576 bugs@openvswitch.org
577 http://openvswitch.org/