2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
6 http://www.apache.org/licenses/LICENSE-2.0
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
14 Convention for heading levels in Open vSwitch documentation:
16 ======= Heading 0 (reserved for the title in a document)
22 Avoid deeper levels because they do not render well.
28 Q: What versions of OpenFlow does Open vSwitch support?
30 A: The following table lists the versions of OpenFlow supported by each
31 version of Open vSwitch:
33 =============== ===== ===== ===== ===== ===== ===== =====
34 Open vSwitch OF1.0 OF1.1 OF1.2 OF1.3 OF1.4 OF1.5 OF1.6
35 =============== ===== ===== ===== ===== ===== ===== =====
36 1.9 and earlier yes --- --- --- --- --- ---
37 1.10, 1.11 yes --- (*) (*) --- --- ---
38 2.0, 2.1 yes (*) (*) (*) --- --- ---
39 2.2 yes (*) (*) (*) (%) (*) ---
40 2.3, 2.4 yes yes yes yes (*) (*) ---
41 2.5, 2.6, 2.7 yes yes yes yes (*) (*) (*)
42 2.8 yes yes yes yes yes (*) (*)
43 =============== ===== ===== ===== ===== ===== ===== =====
46 yes Supported and enabled by default
47 (*) Supported, but missing features, and must be enabled by user.
48 (%) Experimental, unsafe implementation.
50 In any case, the user may override the default:
52 - To enable OpenFlow 1.0, 1.1, 1.2, and 1.3 on bridge br0::
54 $ ovs-vsctl set bridge br0 \
55 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13
57 - To enable OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 on bridge br0::
59 $ ovs-vsctl set bridge br0 \
60 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15
62 - To enable only OpenFlow 1.0 on bridge br0::
64 $ ovs-vsctl set bridge br0 protocols=OpenFlow10
66 All current versions of ovs-ofctl enable only OpenFlow 1.0 by default. Use
67 the -O option to enable support for later versions of OpenFlow in
68 ovs-ofctl. For example::
70 $ ovs-ofctl -O OpenFlow13 dump-flows br0
72 (Open vSwitch 2.2 had an experimental implementation of OpenFlow 1.4 that
73 could cause crashes. We don't recommend enabling it.)
75 :doc:`/topics/openflow` tracks support for OpenFlow 1.1 and later features.
76 When support for OpenFlow 1.5 and 1.6 is solidly implemented, Open vSwitch
77 will enable those version by default.
79 Q: Does Open vSwitch support MPLS?
81 A: Before version 1.11, Open vSwitch did not support MPLS. That is, these
82 versions can match on MPLS Ethernet types, but they cannot match, push, or
83 pop MPLS labels, nor can they look past MPLS labels into the encapsulated
86 Open vSwitch versions 1.11, 2.0, and 2.1 have very minimal support for
87 MPLS. With the userspace datapath only, these versions can match, push, or
88 pop a single MPLS label, but they still cannot look past MPLS labels (even
89 after popping them) into the encapsulated packet. Kernel datapath support
90 is unchanged from earlier versions.
92 Open vSwitch version 2.3 can match, push, or pop a single MPLS label and
93 look past the MPLS label into the encapsulated packet. Both userspace and
94 kernel datapaths will be supported, but MPLS processing always happens in
95 userspace either way, so kernel datapath performance will be disappointing.
97 Open vSwitch version 2.4 can match, push, or pop up to 3 MPLS labels and
98 look past the MPLS label into the encapsulated packet. It will have kernel
99 support for MPLS, yielding improved performance.
101 Q: I'm getting "error type 45250 code 0". What's that?
103 A: This is a Open vSwitch extension to OpenFlow error codes. Open vSwitch
104 uses this extension when it must report an error to an OpenFlow controller
105 but no standard OpenFlow error code is suitable.
107 Open vSwitch logs the errors that it sends to controllers, so the easiest
108 thing to do is probably to look at the ovs-vswitchd log to find out what
111 If you want to dissect the extended error message yourself, the format is
112 documented in include/openflow/nicira-ext.h in the Open vSwitch source
113 distribution. The extended error codes are documented in
114 include/openvswitch/ofp-errors.h.
116 Q: Some of the traffic that I'd expect my OpenFlow controller to see doesn't
117 actually appear through the OpenFlow connection, even though I know that it's
120 A: By default, Open vSwitch assumes that OpenFlow controllers are connected
121 "in-band", that is, that the controllers are actually part of the network
122 that is being controlled. In in-band mode, Open vSwitch sets up special
123 "hidden" flows to make sure that traffic can make it back and forth between
124 OVS and the controllers. These hidden flows are higher priority than any
125 flows that can be set up through OpenFlow, and they are not visible through
126 normal OpenFlow flow table dumps.
128 Usually, the hidden flows are desirable and helpful, but occasionally they
129 can cause unexpected behavior. You can view the full OpenFlow flow table,
130 including hidden flows, on bridge br0 with the command::
132 $ ovs-appctl bridge/dump-flows br0
134 to help you debug. The hidden flows are those with priorities
135 greater than 65535 (the maximum priority that can be set with
138 The ``Documentation/topics/design`` doc describes the in-band model in
141 If your controllers are not actually in-band (e.g. they are on
142 localhost via 127.0.0.1, or on a separate network), then you should
143 configure your controllers in "out-of-band" mode. If you have one
144 controller on bridge br0, then you can configure out-of-band mode
147 $ ovs-vsctl set controller br0 connection-mode=out-of-band
149 Q: Some of the OpenFlow flows that my controller sets up don't seem to apply to
150 certain traffic, especially traffic between OVS and the controller itself.
154 Q: I configured all my controllers for out-of-band control mode but "ovs-appctl
155 bridge/dump-flows" still shows some hidden flows.
157 A: You probably have a remote manager configured (e.g. with "ovs-vsctl
158 set-manager"). By default, Open vSwitch assumes that managers need in-band
159 rules set up on every bridge. You can disable these rules on bridge br0
162 $ ovs-vsctl set bridge br0 other-config:disable-in-band=true
164 This actually disables in-band control entirely for the bridge, as if all
165 the bridge's controllers were configured for out-of-band control.
167 Q: My OpenFlow controller doesn't see the VLANs that I expect.
169 A: See answer under "VLANs", above.
171 Q: I ran ``ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop`` but I got a
172 funny message like this::
174 ofp_util|INFO|normalization changed ofp_match, details:
175 ofp_util|INFO| pre: nw_dst=192.168.0.1
178 and when I ran ``ovs-ofctl dump-flows br0`` I saw that my nw_dst match had
179 disappeared, so that the flow ends up matching every packet.
181 A: The term "normalization" in the log message means that a flow cannot
182 match on an L3 field without saying what L3 protocol is in use. The
183 "ovs-ofctl" command above didn't specify an L3 protocol, so the L3 field
186 In this case, the L3 protocol could be IP or ARP. A correct command for
187 each possibility is, respectively::
189 $ ovs-ofctl add-flow br0 ip,nw_dst=192.168.0.1,actions=drop
193 $ ovs-ofctl add-flow br0 arp,nw_dst=192.168.0.1,actions=drop
195 Similarly, a flow cannot match on an L4 field without saying what L4
196 protocol is in use. For example, the flow match ``tp_src=1234`` is, by
197 itself, meaningless and will be ignored. Instead, to match TCP source port
198 1234, write ``tcp,tp_src=1234``, or to match UDP source port 1234, write
201 Q: How can I figure out the OpenFlow port number for a given port?
203 A: The ``OFPT_FEATURES_REQUEST`` message requests an OpenFlow switch to
204 respond with an ``OFPT_FEATURES_REPLY`` that, among other information,
205 includes a mapping between OpenFlow port names and numbers. From a command
206 prompt, ``ovs-ofctl show br0`` makes such a request and prints the response
209 The Interface table in the Open vSwitch database also maps OpenFlow port
210 names to numbers. To print the OpenFlow port number associated with
211 interface eth0, run::
213 $ ovs-vsctl get Interface eth0 ofport
215 You can print the entire mapping with::
217 $ ovs-vsctl -- --columns=name,ofport list Interface
219 but the output mixes together interfaces from all bridges in the database,
220 so it may be confusing if more than one bridge exists.
222 In the Open vSwitch database, ofport value ``-1`` means that the interface
223 could not be created due to an error. (The Open vSwitch log should
224 indicate the reason.) ofport value ``[]`` (the empty set) means that the
225 interface hasn't been created yet. The latter is normally an intermittent
226 condition (unless ovs-vswitchd is not running).
228 Q: I added some flows with my controller or with ovs-ofctl, but when I run
229 "ovs-dpctl dump-flows" I don't see them.
231 A: ovs-dpctl queries a kernel datapath, not an OpenFlow switch. It won't
232 display the information that you want. You want to use ``ovs-ofctl
233 dump-flows`` instead.
235 Q: It looks like each of the interfaces in my bonded port shows up as an
236 individual OpenFlow port. Is that right?
238 A: Yes, Open vSwitch makes individual bond interfaces visible as OpenFlow
239 ports, rather than the bond as a whole. The interfaces are treated
240 together as a bond for only a few purposes:
242 - Sending a packet to the OFPP_NORMAL port. (When an OpenFlow controller
243 is not configured, this happens implicitly to every packet.)
245 - Mirrors configured for output to a bonded port.
247 It would make a lot of sense for Open vSwitch to present a bond as a single
248 OpenFlow port. If you want to contribute an implementation of such a
249 feature, please bring it up on the Open vSwitch development mailing list at
252 Q: I have a sophisticated network setup involving Open vSwitch, VMs or multiple
253 hosts, and other components. The behavior isn't what I expect. Help!
255 A: To debug network behavior problems, trace the path of a packet,
256 hop-by-hop, from its origin in one host to a remote host. If that's
257 correct, then trace the path of the response packet back to the origin.
259 The open source tool called ``plotnetcfg`` can help to understand the
260 relationship between the networking devices on a single host.
262 Usually a simple ICMP echo request and reply (``ping``) packet is good
263 enough. Start by initiating an ongoing ``ping`` from the origin host to a
264 remote host. If you are tracking down a connectivity problem, the "ping"
265 will not display any successful output, but packets are still being sent.
266 (In this case the packets being sent are likely ARP rather than ICMP.)
268 Tools available for tracing include the following:
270 - ``tcpdump`` and ``wireshark`` for observing hops across network devices,
271 such as Open vSwitch internal devices and physical wires.
273 - ``ovs-appctl dpif/dump-flows <br>`` in Open vSwitch 1.10 and later or
274 ``ovs-dpctl dump-flows <br>`` in earlier versions. These tools allow one
275 to observe the actions being taken on packets in ongoing flows.
277 See ovs-vswitchd(8) for ``ovs-appctl dpif/dump-flows`` documentation,
278 ovs-dpctl(8) for ``ovs-dpctl dump-flows`` documentation, and "Why are
279 there so many different ways to dump flows?" above for some background.
281 - ``ovs-appctl ofproto/trace`` to observe the logic behind how ovs-vswitchd
282 treats packets. See ovs-vswitchd(8) for documentation. You can out more
283 details about a given flow that ``ovs-dpctl dump-flows`` displays, by
284 cutting and pasting a flow from the output into an ``ovs-appctl
285 ofproto/trace`` command.
287 - SPAN, RSPAN, and ERSPAN features of physical switches, to observe what
288 goes on at these physical hops.
290 Starting at the origin of a given packet, observe the packet at each hop in
291 turn. For example, in one plausible scenario, you might:
293 1. ``tcpdump`` the ``eth`` interface through which an ARP egresses a VM,
296 2. ``tcpdump`` the ``vif`` or ``tap`` interface through which the ARP
297 ingresses the host machine.
299 3. Use ``ovs-dpctl dump-flows`` to spot the ARP flow and observe the host
300 interface through which the ARP egresses the physical machine. You may
301 need to use ``ovs-dpctl show`` to interpret the port numbers. If the
302 output seems surprising, you can use ``ovs-appctl ofproto/trace`` to
303 observe details of how ovs-vswitchd determined the actions in the
304 ``ovs-dpctl dump-flows`` output.
306 4. ``tcpdump`` the ``eth`` interface through which the ARP egresses the
309 5. ``tcpdump`` the ``eth`` interface through which the ARP ingresses the
310 physical machine, at the remote host that receives the ARP.
312 6. Use ``ovs-dpctl dump-flows`` to spot the ARP flow on the remote host
313 remote host that receives the ARP and observe the VM ``vif`` or ``tap``
314 interface to which the flow is directed. Again, ``ovs-dpctl show`` and
315 ``ovs-appctl ofproto/trace`` might help.
317 7. ``tcpdump`` the ``vif`` or ``tap`` interface to which the ARP is
320 8. ``tcpdump`` the ``eth`` interface through which the ARP ingresses a VM,
323 It is likely that during one of these steps you will figure out the
324 problem. If not, then follow the ARP reply back to the origin, in reverse.
326 Q: How do I make a flow drop packets?
328 A: To drop a packet is to receive it without forwarding it. OpenFlow
329 explicitly specifies forwarding actions. Thus, a flow with an empty set of
330 actions does not forward packets anywhere, causing them to be dropped. You
331 can specify an empty set of actions with ``actions=`` on the ovs-ofctl
332 command line. For example::
334 $ ovs-ofctl add-flow br0 priority=65535,actions=
336 would cause every packet entering switch br0 to be dropped.
338 You can write "drop" explicitly if you like. The effect is the same.
339 Thus, the following command also causes every packet entering switch br0 to
342 $ ovs-ofctl add-flow br0 priority=65535,actions=drop
344 ``drop`` is not an action, either in OpenFlow or Open vSwitch. Rather, it
345 is only a way to say that there are no actions.
347 Q: I added a flow to send packets out the ingress port, like this::
349 $ ovs-ofctl add-flow br0 in_port=2,actions=2
351 but OVS drops the packets instead.
353 A: Yes, OpenFlow requires a switch to ignore attempts to send a packet out
354 its ingress port. The rationale is that dropping these packets makes it
355 harder to loop the network. Sometimes this behavior can even be
356 convenient, e.g. it is often the desired behavior in a flow that forwards a
357 packet to several ports ("floods" the packet).
359 Sometimes one really needs to send a packet out its ingress port
360 ("hairpin"). In this case, output to ``OFPP_IN_PORT``, which in ovs-ofctl
361 syntax is expressed as just ``in_port``, e.g.::
363 $ ovs-ofctl add-flow br0 in_port=2,actions=in_port
365 This also works in some circumstances where the flow doesn't match on the
366 input port. For example, if you know that your switch has five ports
367 numbered 2 through 6, then the following will send every received packet
368 out every port, even its ingress port::
370 $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
374 $ ovs-ofctl add-flow br0 actions=all,in_port
376 Sometimes, in complicated flow tables with multiple levels of ``resubmit``
377 actions, a flow needs to output to a particular port that may or may not be
378 the ingress port. It's difficult to take advantage of ``OFPP_IN_PORT`` in
379 this situation. To help, Open vSwitch provides, as an OpenFlow extension,
380 the ability to modify the in_port field. Whatever value is currently in
381 the in_port field is the port to which outputs will be dropped, as well as
382 the destination for ``OFPP_IN_PORT``. This means that the following will
383 reliably output to port 2 or to ports 2 through 6, respectively::
385 $ ovs-ofctl add-flow br0 in_port=2,actions=load:0->NXM_OF_IN_PORT[],2
386 $ ovs-ofctl add-flow br0 actions=load:0->NXM_OF_IN_PORT[],2,3,4,5,6
388 If the input port is important, then one may save and restore it on the
391 $ ovs-ofctl add-flow br0 actions=push:NXM_OF_IN_PORT[],\
392 load:0->NXM_OF_IN_PORT[],\
396 Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2 on port 2.
397 I set up flows to forward only traffic destined to the other host and drop
398 other traffic, like this::
400 priority=5,in_port=1,ip,nw_dst=192.168.0.2,actions=2
401 priority=5,in_port=2,ip,nw_dst=192.168.0.1,actions=1
402 priority=0,actions=drop
404 But it doesn't work--I don't get any connectivity when I do this. Why?
406 A: These flows drop the ARP packets that IP hosts use to establish IP
407 connectivity over Ethernet. To solve the problem, add flows to allow ARP
408 to pass between the hosts::
410 priority=5,in_port=1,arp,actions=2
411 priority=5,in_port=2,arp,actions=1
413 This issue can manifest other ways, too. The following flows that match on
414 Ethernet addresses instead of IP addresses will also drop ARP packets,
415 because ARP requests are broadcast instead of being directed to a specific
418 priority=5,in_port=1,dl_dst=54:00:00:00:00:02,actions=2
419 priority=5,in_port=2,dl_dst=54:00:00:00:00:01,actions=1
420 priority=0,actions=drop
422 The solution already described above will also work in this case. It may
423 be better to add flows to allow all multicast and broadcast traffic::
425 priority=5,in_port=1,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=2
426 priority=5,in_port=2,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=1
428 Q: My bridge disconnects from my controller on add-port/del-port.
430 A: Reconfiguring your bridge can change your bridge's datapath-id because
431 Open vSwitch generates datapath-id from the MAC address of one of its
432 ports. In that case, Open vSwitch disconnects from controllers because
433 there's no graceful way to notify controllers about the change of
436 To avoid the behaviour, you can configure datapath-id manually.::
438 $ ovs-vsctl set bridge br0 other-config:datapath-id=0123456789abcdef
440 Q: My controller complains that OVS is not buffering packets.
443 A: "Packet buffering" is an optional OpenFlow feature, and controllers
444 should detect how many "buffers" an OpenFlow switch implements. It was
445 recently noticed that OVS implementation of the buffering feature was not
446 compliant to OpenFlow specifications. Rather than fix it and risk
447 controller incompatibility, the buffering feature is removed as of OVS 2.7.
448 Controllers are already expected to work properly in cases where the switch
449 can not buffer packets, but sends full packets in "packet-in" messages
450 instead, so this change should not affect existing users. After the change
451 OVS always sends the ``buffer_id`` as ``0xffffffff`` in "packet-in"
452 messages and will send an error response if any other value of this field
453 is included in a "packet-out" or a "flow mod" sent by a controller.
455 Packet buffers have limited usefulness in any case. Table-miss packet-in
456 messages most commonly pass the first packet in a microflow to the OpenFlow
457 controller, which then sets up an OpenFlow flow that handles remaining
458 traffic in the microflow without further controller intervention. In such
459 a case, the packet that initiates the microflow is in practice usually
460 small (certainly for TCP), which means that the switch sends the entire
461 packet to the controller and the buffer only saves a small number of bytes
462 in the reverse direction.
464 Q: How does OVS divide flows among buckets in an OpenFlow "select" group?
466 A: In Open vSwitch 2.3 and earlier, Open vSwitch used the destination
467 Ethernet address to choose a bucket in a select group.
469 Open vSwitch 2.4 and later by default hashes the source and destination
470 Ethernet address, VLAN ID, Ethernet type, IPv4/v6 source and destination
471 address and protocol, and for TCP and SCTP only, the source and destination
472 ports. The hash is "symmetric", meaning that exchanging source and
473 destination addresses does not change the bucket selection.
475 Select groups in Open vSwitch 2.4 and later can be configured to use a
476 different hash function, using a Netronome extension to the OpenFlow 1.5+
477 group_mod message. For more information, see
478 Documentation/group-selection-method-property.txt in the Open vSwitch
479 source tree. (OpenFlow 1.5 support in Open vSwitch is still experimental.)
481 Q: I added a flow to accept packets on VLAN 123 and output them on VLAN 456,
484 $ ovs-ofctl add-flow br0 dl_vlan=123,actions=output:1,mod_vlan_vid:456
486 but the packets are actually being output in VLAN 123. Why?
488 A: OpenFlow actions are executed in the order specified. Thus, the actions
489 above first output the packet, then change its VLAN. Since the output
490 occurs before changing the VLAN, the change in VLAN will have no visible
493 To solve this and similar problems, order actions so that changes to
494 headers happen before output, e.g.::
496 $ ovs-ofctl add-flow br0 dl_vlan=123,actions=mod_vlan_vid:456,output:1
498 See also the following question.
500 Q: I added a flow to a redirect packets for TCP port 80 to port 443,
503 $ ovs-ofctl add-flow br0 tcp,tcp_dst=123,actions=mod_tp_dst:443
505 but the packets are getting dropped instead. Why?
507 A: This set of actions does change the TCP destination port to 443, but
508 then it does nothing more. It doesn't, for example, say to continue to
509 another flow table or to output the packet. Therefore, the packet is
512 To solve the problem, add an action that does something with the modified
513 packet. For example::
515 $ ovs-ofctl add-flow br0 tcp,tcp_dst=123,actions=mod_tp_dst:443,normal
517 See also the preceding question.
519 Q: When using the "ct" action with FTP connections, it doesn't seem to matter
520 if I set the "alg=ftp" parameter in the action. Is this required?
522 A: It is advisable to use this option. Some platforms may automatically
523 detect and apply ALGs in the "ct" action regardless of the parameters you
524 provide, however this is not consistent across all implementations. The
525 `ovs-ofctl(8) <http://openvswitch.org/support/dist-docs/ovs-ofctl.8.html>`_
526 man pages contain further details in the description of the ALG parameter.