23/03/2016 Open 

vSwitch Cheat Sheet

The Random Security Guy

RANDOM SECURITY, NETWORKING, AND ABSTRACTED COMPUTING

HOME   ABOUT   CONTACT   GITHUB   PUBLIC KEY  RESUME

POSTED IN OPENSTACK, OPENVSWITCH, SDN

Open vSwitch Cheat Sheet

SUNDAY, DECEMBER 28, 2014

Before I begin, for those unfamiliar with Open vSwitch, please

check out my friend David Mahler's YouTube page for
comprehensive introductory videos.

Over the past year I've spent some time compiling troubleshooting
documents and procedures for all things cloud (OpenStack, SDN,
Open vSwitch, etc). I wanted to make a series on 'cheat sheets', or
common day to day con䅘‫ﰀ‬guration/troubleshooting commands and
techniques for di섵媀erent cloud components.

First on the list is Open vSwitch (aka OVS), which has become an
integral part of OpenStack networking. It provides the ability to
replicate many of the features of a traditional layer 2 switch, while

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 1/8
23/03/2016 Open vSwitch Cheat Sheet

providing advanced features that allow organizations to scale their

cloud environments quickly.

Let's get started!

Base commands

OVS is feature rich with di섵媀erent con䅘‫ﰀ‬guration commands, but the

majority of your con䅘‫ﰀ‬guration and troubleshooting can be
accomplished with the following 4 commands:

ovs-vsctl : Used for con䅘‫ﰀ‬guring the ovs-vswitchd

con䅘‫ﰀ‬guration database (known as ovs-db)
ovs-ofctl : A command line tool for monitoring and
administering OpenFlow switches
ovs-dpctl : Used to administer Open vSwitch datapaths
ovs−appctl : Used for querying and controlling Open vSwitch
daemons

ovs-vsctl

This tool is used for con䅘‫ﰀ‬guration and viewing OVS switch

operations. Port con䅘‫ﰀ‬guration, bridge additions/deletions, bonding,
and VLAN tagging are just some of the options that are available
with this command.

Below are the most useful 'show' commands:

ovs‐vsctl –V : Prints the current version of openvswitch.

ovs‐vsctl show : Prints a brief overview of the switch database
con䅘‫ﰀ‬guration.
ovs‐vsctl list‐br : Prints a list of con䅘‫ﰀ‬gured bridges
ovs‐vsctl list‐ports <bridge> : Prints a list of ports on a speci䅘‫ﰀ‬c bridge.
ovs‐vsctl list interface : Prints a list of interfaces.

The above should be fairly self explanatory. Below are the common

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 2/8
23/03/2016 Open vSwitch Cheat Sheet

switch con䅘‫ﰀ‬guration commands:

ovs‐vsctl add‐br <bridge> : Creates a bridge in the switch database.

ovs‐vsctl add‐port <bridge> <interface> : Binds an interface (physical or
virtual) to a bridge.
ovs‐vsctl add‐port <bridge> <interface> tag=<VLAN number> : Converts port
to an access port on speci䅘‫ﰀ‬ed VLAN (by default all OVS ports are
VLAN trunks).
ovs‐vsctl set interface <interface> type=patch options:peer=<interface> :
Used to create patch ports to connect two or more bridges together.

The 䅘‫ﰀ‬rst 3 commands above are fairly standard, so why did I

include the last one? This is a con䅘‫ﰀ‬guration I've been using for
tra䄯㠀c interception when connecting one bridge to another. I'll
explain in more in detail in a future post :)

ovs-ofctl

This tool is used for administering and monitoring OpenFlow

switches. Even if OVS isn't con䅘‫ﰀ‬gured for centralized
administration, ovs-ofctl can be used to show the current state of
OVS including features, con䅘‫ﰀ‬guration, and table entries.

Below are common show commands:

ovs‐ofctl show <bridge> : Shows OpenFlow features and port

descriptions.
ovs‐ofctl snoop <bridge> : Snoops tra䄯㠀c to and from the bridge and
prints to console.
ovs‐ofctl dump‐flows <bridge> <flow> : Prints 섟쀀ow entries of speci䅘‫ﰀ‬ed
bridge. With the 섟쀀ow speci䅘‫ﰀ‬ed, only the matching 섟쀀ow will be
printed to console. If the 섟쀀ow is omitted, all 섟쀀ow entries of the
bridge will be printed.
ovs‐ofctl dump‐ports‐desc <bridge> : Prints port statistics. This will show
detailed information about interfaces in this bridge, include the
http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 3/8
23/03/2016 Open vSwitch Cheat Sheet

state, peer, and speed information. Very useful

ovs‐ofctl dump‐tables‐desc <bridge> : Similar to above but prints the
descriptions of tables belonging to the stated bridge.

ovs-ofctl dump-ports-desc is useful for viewing port connectivity.

This is useful in detecting errors in your NIC to bridge bonding.

Below are the common con䅘‫ﰀ‬gurations used with the ovs-ofctl tool:

ovs‐ofctl add‐flow <bridge> <flow> : Add a static 섟쀀ow to the speci䅘‫ﰀ‬ed

bridge. Useful in de䅘‫ﰀ‬ning conditions for a 섟쀀ow (i.e. prioritize, drop,
etc).
ovs‐ofctl del‐flows <bridge> <flow> : Delete the 섟쀀ow entries from 섟쀀ow
table of stated bridge. If the 섟쀀ow is omitted, all 섟쀀ows in speci䅘‫ﰀ‬ed
bridge will be deleted.

The above commands can take many arguments regarding di섵媀erent

䅘‫ﰀ‬eld to match. They can be used for simple source/destination 섟쀀ow
additions to complex L3 rewriting (SNAT, DNAT, etc). You can even
build a functional router with them :)

ovs-dpctl

ovs-dpctl is very similar to ovs-ofctl in that they both show 섟쀀ow

table entries. The 섟쀀ows that ovs-dpctl prints are always an exact
match and re섟쀀ect packets that have actually passed through the
system within the last few seconds. ovs-dpctl queries a kernel
datapath and not an OpenFlow switch. This is why it's useful for
debugging 섟쀀ow data.

Starting in version 1.9, OVS switched to using a single datapath that

is shared by all bridges of that type. In order to create a new
datapath, use the following:

ovs‐dpctl add‐dp dp1

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 4/8
23/03/2016 Open vSwitch Cheat Sheet

ovs‐dpctl add‐if dp1 eth0

Then use the following to view 섟쀀ow table data:

ovs‐dpctl dump‐flows

ovs-appctl

OVS is comprised of several daemons that manage and control an

Open vSwitch switch. ovs-appctl is a utility for managing these
daemons at runtime. It is useful for con䅘‫ﰀ‬guring log module settings
as well as viewing all OpenFlow 섟쀀ows, including hidden ones.

The following are useful commands to use:

ovs‐appctl bridge/dump‐flows <bridge> : Dumps OpenFlow 섟쀀ows,

including hidden 섟쀀ows. Useful for troubleshooting in-band issues.
ovs‐appctl dpif/dump‐flows <bridge> : Dumps datapath 섟쀀ows for only the
speci䅘‫ﰀ‬ed bridge, regardless of the type.
ovs‐appctl vlog/list : Lists the known logging modules and their
current levels. Use ovs-appctl vlog/set to set/change the module log
level.
ovs‐appctl ofproto/trace : Used to show entire 섟쀀ow 䅘‫ﰀ‬eld of a given
섟쀀ow (섟쀀ow, matched rule, action taken).

Now, with all of these tools at your disposal, let's go over some
common troubleshooting scenarios.

Troubleshooting

One of the most common issues I've encountered has been

problems with linking an interface to an OVS bridge. Take this
con䅘‫ﰀ‬guration for example:

ovs-vsctl add-br brbm

ovs-vsctl add-port brbm eth2

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 5/8
23/03/2016 Open vSwitch Cheat Sheet

The above con䅘‫ﰀ‬guration creates an OVS bridge (brbm) and links the
physical interface eth2 to brbm. If you've enabled ip_forwarding
and have created the bridge interfaces in your network interfaces
䅘‫ﰀ‬le but have zero connectivity to the new interface, then how do
you troubleshoot? Let's use some of the tools above to verify our
con䅘‫ﰀ‬guration:

root@testnode1:~# ovs‐vsctl show 
cae63bc8‐ba98‐451a‐a652‐a3b0e8a0f553 
    Bridge brbm 
        Port "eth2" 
            Interface "eth2" 
        Port brbm 
            Interface brbm 
                type: internal 

root@testnode1:~# ovs‐vsctl list‐ports brbm 
eth2 

root@testnode1:~# ovs‐ofctl dump‐ports brbm 
OFPST_PORT reply (xid=0x2): 1 ports 
  port LOCAL: rx pkts=23, bytes=1278, drop=0, errs=0, frame=0, 
over=0, crc=0 
           tx pkts=369369, bytes=62820789, drop=0, errs=0, coll=0 

root@testnode1:~# ovs‐ofctl dump‐ports‐desc brbm 
OFPST_PORT_DESC reply (xid=0x2): 
 LOCAL(brbm): addr:78:e7:d1:24:73:85 
 config:     0 
 state:      0 
 speed: 0 Mbps now, 0 Mbps max 

root@testnode1:/etc/network# ifconfig 
brbm      Link encap:Ethernet  HWaddr 78:e7:d1:24:73:85   
          inet addr:10.23.32.15  Bcast:0.0.0.0  Mask:255.255.248.0 
          inet6 addr: fe80::16:e1ff:fe1f:f3e4/64 Scope:Link 
          UP BROADCAST RUNNING  MTU:1500  Metric:1 
          RX packets:369369 errors:0 dropped:159944 overruns:0 
frame:0 
          TX packets:23 errors:0 dropped:0 overruns:0 carrier:0 
          collisions:0 txqueuelen:0  
          RX bytes:62820789 (62.8 MB)  TX bytes:1278 (1.2 KB) 

eth2      Link encap:Ethernet  HWaddr 78:e7:d1:24:73:85   
          inet6 addr: fe80::7ae7:d1ff:fe24:7385/64 Scope:Link 
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1 
          RX packets:14148 errors:0 dropped:68 overruns:0 frame:0 
          TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 6/8
23/03/2016 Open vSwitch Cheat Sheet

          collisions:0 txqueuelen:1000  
          RX bytes:2198636 (2.1 MB)  TX bytes:648 (648.0 B) 

lo        Link encap:Local Loopback   
          inet addr:127.0.0.1  Mask:255.0.0.0 
          inet6 addr: ::1/128 Scope:Host 
          UP LOOPBACK RUNNING  MTU:65536  Metric:1 
          RX packets:17701 errors:0 dropped:0 overruns:0 frame:0 
          TX packets:17701 errors:0 dropped:0 overruns:0 carrier:0 
          collisions:0 txqueuelen:0  
          RX bytes:1487216 (1.4 MB)  TX bytes:1487216 (1.4 MB) 

root@testnode1:/etc/network# cat /proc/sys/net/ipv4/ip_forward 
1 

From the output above I see that although the OVS and interfaces
䅘‫ﰀ‬le looks correct, I do not see any port tra䄯㠀c aside from LOCAL.
LOCAL tra䄯㠀c is tra䄯㠀c generated from the host (ICMP in/out, ARP,
etc). What is missing from the original OVS con䅘‫ﰀ‬guration statement
is a restart of the networking stack. After the restart, we can see
proper 섟쀀ow generation:

root@testnode1:~# ovs‐ofctl dump‐ports‐desc brbm 
OFPST_PORT_DESC reply (xid=0x2): 
 1(eth2): addr:78:e7:d1:24:73:85 
     config:     0 
     state:      0 
     current:    10GB‐FD FIBER 
     advertised: 10GB‐FD FIBER 
     supported:  10GB‐FD FIBER 
     speed: 10000 Mbps now, 10000 Mbps max 

root@testnode1:~# ovs‐ofctl dump‐ports brbm 
OFPST_PORT reply (xid=0x2): 3 ports 
  port  5: rx pkts=6071934, bytes=37086750067, drop=0, errs=0, 
frame=0, over=0, crc=0 
       tx pkts=6888905, bytes=626021363, drop=0, errs=0, coll=0 
  port  1: rx pkts=32317009, bytes=32290813174, drop=0, errs=0, 
frame=0, over=0, crc=0 
       tx pkts=25212056, bytes=83553302356, drop=0, errs=0, coll=0 
  port LOCAL: rx pkts=12293904, bytes=1780442549, drop=0, errs=0, 
frame=0, over=0, crc=0 
       tx pkts=24816664, bytes=31363410668, drop=0, errs=0, coll=0 

Now that's a proper link :)

CONCLUSION
http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 7/8
23/03/2016 Open vSwitch Cheat Sheet

CONCLUSION
Open vSwitch provides a handful of useful tools for troubleshooting
di섵媀erent con䅘‫ﰀ‬gurations. I've only covered a handful of commands
that I've used but may turn this into a more in depth series.

Until next time...

0 Comments therandomsecurityguy 
1  Login

  Recommend ⤤ Share Sort by Best

Start the discussion…

Be the first to comment.

✉ Subscribe d Add Disqus to your site Add Disqus Add ὑ Privacy

SHARE THIS POST    

AUTHOR
dc

© 2016 THE RANDOM SECURITY GUY. ALL RIGHTS RESERVED.

PROUDLY PUBLISHED WITH 

http://therandomsecurityguy.com/openvswitch­cheat­sheet/ 8/8