From c483d489caeec8b38991065580365e8a2b34237e Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Tue, 12 Jun 2012 09:40:11 -0700 Subject: [PATCH] Add a FAQ. I wrote most of this myself. The answer to "I can't seem to use Open vSwitch in a wireless network" is based on a response by Jesse Gross: http://openvswitch.org/pipermail/discuss/2011-January/004707.html Signed-off-by: Ben Pfaff --- FAQ | 322 +++++++++++++++++++++++++++++++++ Makefile.am | 1 + NEWS | 1 + README | 2 + debian/automake.mk | 1 + debian/openvswitch-common.docs | 1 + rhel/openvswitch.spec.in | 3 +- 7 files changed, 330 insertions(+), 1 deletion(-) create mode 100644 FAQ create mode 100644 debian/openvswitch-common.docs diff --git a/FAQ b/FAQ new file mode 100644 index 00000000..678ca2cf --- /dev/null +++ b/FAQ @@ -0,0 +1,322 @@ + Open vSwitch + +Frequently Asked Questions +========================== + +Configuration Problems +---------------------- + +Q: I created a bridge and added my Ethernet port to it, using commands + like these: + + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 + + and as soon as I ran the "add-port" command I lost all connectivity + through eth0. Help! + +A: A physical Ethernet device that is part of an Open vSwitch bridge + should not have an IP address. If one does, then that IP address + will not be fully functional. + + You can restore functionality by moving the IP address to an Open + vSwitch "internal" device, such as the network device named after + the bridge itself. For example, assuming that eth0's IP address is + 192.168.128.5, you could run the commands below to fix up the + situation: + + ifconfig eth0 0.0.0.0 + ifconfig br0 192.168.128.5 + + (If your only connection to the machine running OVS is through the + IP address in question, then you would want to run all of these + commands on a single command line, or put them into a script.) If + there were any additional routes assigned to eth0, then you would + also want to use commands to adjust these routes to go through br0. + + If you use DHCP to obtain an IP address, then you should kill the + DHCP client that was listening on the physical Ethernet interface + (e.g. eth0) and start one listening on the internal interface + (e.g. br0). You might still need to manually clear the IP address + from the physical interface (e.g. with "ifconfig eth0 0.0.0.0"). + + There is no compelling reason why Open vSwitch must work this way. + However, this is the way that the Linux kernel bridge module has + always worked, so it's a model that those accustomed to Linux + bridging are already used to. Also, the model that most people + expect is not implementable without kernel changes on all the + versions of Linux that Open vSwitch supports. + + By the way, this issue is not specific to physical Ethernet + devices. It applies to all network devices except Open vswitch + "internal" devices. + +Q: I created a bridge and added a couple of Ethernet ports to it, + using commands like these: + + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 + ovs-vsctl add-port br0 eth1 + + and now my network seems to have melted: connectivity is unreliable + (even connectivity that doesn't go through Open vSwitch), all the + LEDs on my physical switches are blinking, and wireshark shows + duplicated packets. + +A: More than likely, you've looped your network. Probably, eth0 and + eth1 are connected to the same physical Ethernet switch. This + yields a scenario where OVS receives a broadcast packet on eth0 and + sends it out on eth1, then the physical switch connected to eth1 + sends the packet back on eth0, and so on forever. More complicated + scenarios, involving a loop through multiple switches, are possible + too. + + The solution depends on what you are trying to do: + + - If you added eth0 and eth1 to get higher bandwidth or higher + reliability between OVS and your physical Ethernet switch, + use a bond. The following commands create br0 and then add + eth0 and eth1 as a bond: + + ovs-vsctl add-br br0 + ovs-vsctl add-bond br0 bond0 eth0 eth1 + + Bonds have tons of configuration options. Please read the + documentation on the Port table in ovs-vswitchd.conf.db(5) + for all the details. + + - Perhaps you don't actually need eth0 and eth1 to be on the + same bridge. For example, if you simply want to be able to + connect each of them to virtual machines, then you can put + each of them on a bridge of its own: + + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 + + ovs-vsctl add-br br1 + ovs-vsctl add-port br1 eth1 + + and then connect VMs to br0 and br1. (A potential + disadvantage is that traffic cannot directly pass between br0 + and br1. Instead, it will go out eth0 and come back in eth1, + or vice versa.) + + - If you have a redundant or complex network topology and you + want to prevent loops, turn on spanning tree protocol (STP). + The following commands create br0, enable STP, and add eth0 + and eth1 to the bridge. The order is important because you + don't want have to have a loop in your network even + transiently: + + ovs-vsctl add-br br0 + ovs-vsctl set bridge br0 stp_enable=true + ovs-vsctl add-port br0 eth0 + ovs-vsctl add-port br0 eth1 + + The Open vSwitch implementation of STP is not well tested. + Please report any bugs you observe, but if you'd rather avoid + acting as a beta tester then another option might be your + best shot. + +Q: I can't seem to use Open vSwitch in a wireless network. + +A: Wireless base stations generally only allow packets with the source + MAC address of NIC that completed the initial handshake. + Therefore, without MAC rewriting, only a single device can + communicate over a single wireless link. + + This isn't specific to Open vSwitch, it's enforced by the access + point, so the same problems will show up with the Linux bridge or + any other way to do bridging. + + +VLANs +----- + +Q: VLANs don't work. + +A: Many drivers in Linux kernels before version 3.3 had VLAN-related + bugs. If you are having problems with VLANs that you suspect to be + driver related, then you have several options: + + - Upgrade to Linux 3.3 or later. + + - Build and install a fixed version of the particular driver + that is causing trouble, if one is available. + + - Use a NIC whose driver does not have VLAN problems. + + - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later + that works around bugs in kernel drivers. To enable VLAN + splinters on interface eth0, use the command: + + ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true + + For VLAN splinters to be effective, Open vSwitch must know + which VLANs are in use. See the "VLAN splinters" section in + the Interface table in ovs-vswitchd.conf.db(5) for details on + how Open vSwitch infers in-use VLANs. + + VLAN splinters increase memory use and reduce performance, so + use them only if needed. + + - Apply the "vlan workaround" patch from the XenServer kernel + patch queue, build Open vSwitch against this patched kernel, + and then use ovs-vlan-bug-workaround(8) to enable the VLAN + workaround for each interface whose driver is buggy. + + (This is a nontrivial exercise, so this option is included + only for completeness.) + + It is not always easy to tell whether a Linux kernel driver has + buggy VLAN support. The ovs-vlan-test(8) and ovs-test(8) utilities + can help you test. See their manpages for details. Of the two + utilities, ovs-test(8) is newer and more thorough, but + ovs-vlan-test(8) may be easier to use. + +Q: VLANs still don't work. I've tested the driver so I know that it's OK. + +A: Do you have VLANs enabled on the physical switch that OVS is + attached to? Make sure that the port is configured to trunk the + VLAN or VLANs that you are using with OVS. + +Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch + and to its destination host, but OVS seems to drop incoming return + traffic. + +A: It's possible that you have the VLAN configured on your physical + switch as the "native" VLAN. In this mode, the switch treats + incoming packets either tagged with the native VLAN or untagged as + part of the native VLAN. It may also send outgoing packets in the + native VLAN without a VLAN tag. + + If this is the case, you have two choices: + + - Change the physical switch port configuration to tag packets + it forwards to OVS with the native VLAN instead of forwarding + them untagged. + + - Change the OVS configuration for the physical port to a + native VLAN mode. For example, the following sets up a + bridge with port eth0 in "native-tagged" mode in VLAN 9: + + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged + + In this situation, "native-untagged" mode will probably work + equally well. Refer to the documentation for the Port table + in ovs-vswitchd.conf.db(5) for more information. + +Q: Can I configure an IP address on a VLAN? + +A: Yes. Use an "internal port" configured as an access port. For + example, the following configures IP address 192.168.0.7 on VLAN 9. + That is, OVS will forward packets from eth0 to 192.168.0.7 only if + they have an 802.1Q header with VLAN 9. Conversely, traffic + forwarded from 192.168.0.7 to eth0 will be tagged with an 802.1Q + header with VLAN 9: + + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 + ovs-vsctl add-port br0 vlan9 tag=9 -- set interface vlan9 type=internal + ifconfig vlan9 192.168.0.7 + +Q: My OpenFlow controller doesn't see the VLANs that I expect. + +A: The configuration for VLANs in the Open vSwitch database (e.g. via + ovs-vsctl) only affects traffic that goes through Open vSwitch's + implementation of the OpenFlow "normal switching" action. By + default, when Open vSwitch isn't connected to a controller and + nothing has been manually configured in the flow table, all traffic + goes through the "normal switching" action. But, if you set up + OpenFlow flows on your own, through a controller or using ovs-ofctl + or through other means, then you have to implement VLAN handling + yourself. + + You can use "normal switching" as a component of your OpenFlow + actions, e.g. by putting "normal" into the lists of actions on + ovs-ofctl or by outputting to OFPP_NORMAL from an OpenFlow + controller. This will only be suitable for some situations, + though. + + +Controllers +----------- + +Q: I'm getting "error type 45250 code 0". What's that? + +A: This is a Open vSwitch extension to OpenFlow error codes. Open + vSwitch uses this extension when it must report an error to an + OpenFlow controller but no standard OpenFlow error code is + suitable. + + Open vSwitch logs the errors that it sends to controllers, so the + easiest thing to do is probably to look at the ovs-vswitchd log to + find out what the error was. + + If you want to dissect the extended error message yourself, the + format is documented in include/openflow/nicira-ext.h in the Open + vSwitch source distribution. The extended error codes are + documented in lib/ofp-errors.h. + +Q1: Some of the traffic that I'd expect my OpenFlow controller to see + doesn't actually appear through the OpenFlow connection, even + though I know that it's going through. +Q2: Some of the OpenFlow flows that my controller sets up don't seem + to apply to certain traffic, especially traffic between OVS and + the controller itself. + +A: By default, Open vSwitch assumes that OpenFlow controllers are + connected "in-band", that is, that the controllers are actually + part of the network that is being controlled. In in-band mode, + Open vSwitch sets up special "hidden" flows to make sure that + traffic can make it back and forth between OVS and the controllers. + These hidden flows are higher priority than any flows that can be + set up through OpenFlow, and they are not visible through normal + OpenFlow flow table dumps. + + Usually, the hidden flows are desirable and helpful, but + occasionally they can cause unexpected behavior. You can view the + full OpenFlow flow table, including hidden flows, on bridge br0 + with the command: + + ovs-appctl bridge/dump-flows br0 + + to help you debug. The hidden flows are those with priorities + greater than 65535 (the maximum priority that can be set with + OpenFlow). + + The DESIGN file at the top level of the Open vSwitch source + distribution describes the in-band model in detail. + + If your controllers are not actually in-band (e.g. they are on + localhost via 127.0.0.1, or on a separate network), then you should + configure your controllers in "out-of-band" mode. If you have one + controller on bridge br0, then you can configure out-of-band mode + on it with: + + ovs-vsctl set controller br0 connection-mode=out-of-band + +Q: I configured all my controllers for out-of-band control mode but + "ovs-appctl bridge/dump-flows" still shows some hidden flows. + +A: You probably have a remote manager configured (e.g. with "ovs-vsctl + set-manager"). By default, Open vSwitch assumes that managers need + in-band rules set up on every bridge. You can disable these rules + on bridge br0 with: + + ovs-vsctl set bridge br0 other-config:disable-in-band=true + + This actually disables in-band control entirely for the bridge, as + if all the bridge's controllers were configured for out-of-band + control. + +Q: My OpenFlow controller doesn't see the VLANs that I expect. + +A: See answer under "VLANs", above. + +Contact +------- + +bugs@openvswitch.org +http://openvswitch.org/ diff --git a/Makefile.am b/Makefile.am index 4b6156d1..14604e88 100644 --- a/Makefile.am +++ b/Makefile.am @@ -41,6 +41,7 @@ PYCOV_CLEAN_FILES = build-aux/check-structs,cover EXTRA_DIST = \ CodingStyle \ DESIGN \ + FAQ \ INSTALL.KVM \ INSTALL.Libvirt \ INSTALL.Linux \ diff --git a/NEWS b/NEWS index 8cd38dd7..f5b7ad52 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,6 @@ post-v1.7.0 ------------------------ + - New FAQ. Please send updates and additions! - ovs-ofctl: - "mod-port" command can now control all OpenFlow config flags. - Added support for arbitrary ethernet masks diff --git a/README b/README index 251a92e2..aa317820 100644 --- a/README +++ b/README @@ -90,6 +90,8 @@ What other documentation is available? To install Open vSwitch on a regular Linux machine, read INSTALL.Linux. +For answers to common questions, read FAQ. + To use Open vSwitch as a drop-in replacement for the Linux bridge, read INSTALL.bridge. diff --git a/debian/automake.mk b/debian/automake.mk index 046b7c43..ae821682 100644 --- a/debian/automake.mk +++ b/debian/automake.mk @@ -12,6 +12,7 @@ EXTRA_DIST += \ debian/openvswitch-brcompat.postinst \ debian/openvswitch-brcompat.postrm \ debian/openvswitch-common.dirs \ + debian/openvswitch-common.docs \ debian/openvswitch-common.install \ debian/openvswitch-common.manpages \ debian/openvswitch-controller.README.Debian \ diff --git a/debian/openvswitch-common.docs b/debian/openvswitch-common.docs new file mode 100644 index 00000000..d6360a1c --- /dev/null +++ b/debian/openvswitch-common.docs @@ -0,0 +1 @@ +FAQ diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 12045cb3..54442fbf 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -50,7 +50,7 @@ rhel_cp usr_share_openvswitch_scripts_sysconfig.template 0644 docdir=$RPM_BUILD_ROOT/usr/share/doc/openvswitch-%{version} install -d -m755 "$docdir" -install -m 0644 rhel/README.RHEL "$docdir" +install -m 0644 FAQ rhel/README.RHEL "$docdir" install python/compat/uuid.py $RPM_BUILD_ROOT/usr/share/openvswitch/python install python/compat/argparse.py $RPM_BUILD_ROOT/usr/share/openvswitch/python @@ -152,5 +152,6 @@ exit 0 /usr/share/openvswitch/scripts/ovs-save /usr/share/openvswitch/scripts/sysconfig.template /usr/share/openvswitch/vswitch.ovsschema +/usr/share/doc/openvswitch-%{version}/FAQ /usr/share/doc/openvswitch-%{version}/README.RHEL /var/lib/openvswitch -- 2.30.2