OpenFlow HOTI 2008 Hands-on Tutorial Instructions

From OpenFlow Wiki

Contents 1 Login to machine 2 Login to VM 3 OpenFlow Regression Tests 4 Wireshark Plugin 5 NOX VM Environment 6 OpenFlow Exercises 7 Debugging Notes 7.1 Part 1: Hub 7.2 Part 2: Learning Switch 7.3 Part 3: Flow Switch 7.4 Part 4: Beyond

Login to machine

The username is 'hoti' and the password should be available on the whiteboard or projector.

Once logged in, bring up VMWare Player (Applications->System Tools->VMWare Player)

Click on 'Open an existing Virtual Machine' and select 'Deb\ Minimal.vmwarevm' in /home/hoti. Your VM should boot.

Login to VM

The VM login is 'openflow', and the password is 'openflow' too.

First, find the IP address of your VM:

ifconfig eth0 | grep inet

For the rest of this tutorial, we will NOT be using the original VMWare window - we'll be using other SSH terminals. Open a terminal window, by clicking on Applications->Accessories->Terminal.

Now, SSH into your machine, with X forwarding enabled:

ssh -X root@X.X.X.X

Minimize the VMWare window.

OpenFlow Regression Tests

First, we'll run through the OpenFlow Regression Test Suite, which is available for download from OpenFlowSwitch.org. The suite is meant to ensure a base level of compatibility between different vendors' OpenFlow implementations. In addition, it's a useful tool for bringing up you own OpenFlow implementation, feature-by-feature.

The test suite has two main parts. Black-Box Tests test specific OpenFlow features and corner cases, with a Perl socket acting as the OpenFlow controller. The Learning Switch tests use the provided C kernel-space or user-space controller, and ensure that the combination of an OpenFlow switch plus the sample controller appear from the outside as an Ethernet learning switch.

Today, we'll only run the Learning Switch tests, as they take less time to run and show a variety of OpenFlow messages.

Source the environment variables:

cd /home/openflow
source env_vars

To simplify testing, we'll use virtual ethernet pairs, which let us send raw packets to a virtual wire and have the packet pop back into the system. Four of the pairs are own by Perl code that can send or receive packets, while the other four are owned by the OpenFlow switch. We can tcpdump on these ports, too.

Set up virtual ethernet pairs:

cd openflow-test-v0.8.1-r2/bin
./veth_setup.pl

Verify that you now have veth0...veth7:

ifconfig -a | grep veth

Verify your setup by running regression tests:

of_kmod_veth_test.pl

All tests should pass, but occasionally the first test will miss packets. If it runs OK the second time, don't worry about it. The tests automatically print out any missing or unexpected packets for each test.

Wireshark Plugin

Next, we'll try out the OpenFlow Wireshark Plugin. This is hugely useful when debugging both virtual and physical OpenFlow networks, as it lets you identify malformed OpenFlow packets and go straight to the packet fields you want, without having to consult the OpenFlow spec quite as frequently.

Open wireshark:

cd /home/openflow/wireshark-1.0.2
./wireshark &

NOTE: the version of Wireshark included in the VM is hacked, due to an issue with the current OpenFlow plugin makefile. Make sure to add the './' before Wireshark, or you'll experience errors. This will be fixed soon.

NOTE: when you start up Wireshark, there is a modal warning message that gets hidden behind the main display, and it prevents you from clicking on anything in the main Wireshark window. Drag the main window and click 'OK' to get past the warning.

In Wireshark, click on 'Expression', click on the left box, then type 'ofp'. If you see OFP (OpenFlow Protocol) listed, you can filter on OpenFlow packets. Click 'OK', and now the filter string 'of' will appear in the filter box in green. Click Apply to apply the filter.

We'll want to see packets in real time. To set Wireshark to this, go to Capture->Options->Display Options and click on 'Update list of packets in real time'. Also select "Automatic scrolling in live capture' for auto-scroll and 'Hide capture info dialog' for a little more screen space. Click 'Start'.

Click Capture->Stop.

Click on Capture->Interfaces and click 'Start' next to the 'lo' interface.

Add 'of' to the filter box and press return. Packets will be arriving, as indicated by the P counter at the bottom of the window, but none are displayed because all are non-OpenFlow. To generate some openflow packets, we'll run the test suite.

Run the tests, and watch the Wireshark window.

of_kmod_veth_test.pl

Click in the middle third of the Wireshark window on the OpenFlow portion - you can inspect individual packet fields.

(Not required for tutorial) To run a single test with virtual Ethernet pairs, do the following:

cd openflow-test-v0.8.1-r2/projects/{black_box|learning_switch}/<test_name>
of_kmod_veth_setup.pl; ./run.pl --map=$OFT_ROOT/bin/veth.map; of_kmod_veth_teardown.pl 

For example, to run the most basic test that sends a features request to the switch and expects a features reply, run:

cd openflow-test-v0.8.1-r2/projects/learning_switch/test_unicast_unknown
of_kmod_veth_setup.pl; ./run.pl --map=$OFT_ROOT/bin/veth.map; of_kmod_veth_teardown.pl

NOX VM Environment

From noxrepo.org:

NOX is an open-source platform that simplifies the creation of software for controlling or monitoring networks. Programs written within NOX (using either C++ or Python) have flow-level control of the network. This means that they can determine which flows are allowed on the network and the path they take. In addition, NOX provides programs with access to the network state including the network topology and the location of all detected hosts.

NOX is an another example of an OpenFlow controller, one that provides visibility and control into a full network of OpenFlow switches. We'll be using it for tutorial exercises.

Next, we'll run through noxrepo.org VM scripts, which set up an entire network of OpenFlow switches, controller, and hosts. Yes, there are two levels of virtual machine here - the VMWare Debian install, and the OpenFlow switch and hosts that run as QEMU instances with a minimal Debian kernel and little memory. The connection between VM is provided by Virtual Distributed Ethernet (VDE). The noxrepo.org scripts abstract VDE and make it very easy to configure different numbers of hosts and switches. Each QEMU VM takes about 70MB of memory; the size of your simulated network is limited only by machine memory and CPU time.

The following instructions are derived from those at noxrepo.org, "Setting Up a Virtual Test Environment". Nicira Networks, creators of NOX, deserve credit for these.

Run the script to spawn xterms with monitor running (X forwarding assumed). These xterms provide a window into each VM, and can be closed and reopened without affecting the VMs.

cd /home/openflow
./spawn_xterms.sh

Each xterm should say "Waiting for <vm_name> VM...".

Start up the VMs:

cd vm
start-test-vm vms-1sw-3hsts.conf

This should take a few minutes; in the meantime, move on to the next step.

While each xterm is showing a , go ahead and start NOX. Port 975 is the default OpenFlow unsecured TCP port, and the one used by the Wireshark plugin to identify OpenFlow packets. We'll start NOX with a minimal configuration, but you can run multiple NOX applications at the same time to get additional features like topology discovery, a web interface, and authentication. Pyswitch is a flow-based learning switch.

cd /home/openflow/nox-0.2.1/src
./nox_core -v -i ptcp:975 pyswitch

Once you’ve got a boot prompt, log into the virtual machine monitoring ‘openflow1’ using root/root and issue the following commands:

cd /cdrom
dhclient # should connect to eth1
ping 10.0.2.2 # verify that you can ping the host OS
insmod ./openflow_mod.ko # run the openflow datapath
./dpctl adddp nl:0 # create a new openflow datapath
./dpctl addif nl:0 eth0 # connect end1
./dpctl addif nl:0 eth2 # connect end2
./dpctl addif nl:0 eth3 # connect end3
./secchan nl:0 tcp:10.0.2.2:975 # run secure channel and connect to host

Log into the other three virtual machines (using root/root) and give the interfaces different IP addresses on the same subnet:

# On the end1 VM
ifconfig eth0 10.0.0.1
# On the end2 VM
ifconfig eth0 10.0.0.2
# On the end3 VM
ifconfig eth0 10.0.0.3 

If all went well, you should be able to ping ‘end1’ from ‘end2’ and vice versa.

# On the end1 VM 
ping 10.0.0.2

Be sure to watch the OpenFlow Protocol messages in Wireshark!

Now, close down NOX with Ctrl-C, plus go into end1 and Ctrl-C to close secchan.

OpenFlow Exercises

In this set of exercises, you'll start with a NOX application that controls an OpenFlow network as a hub. You'll turn the hub into a learning switch, and then into a faster flow switch.

You'll be modifying the file 'tutorial.py' in ~/nox-0.2.1/src/nox/apps/examples. Open this file in the editor of your choice, within the primary VM. If your editor of choice is missing, feel free to install it, for example:

apt-get install emacs

Debugging Notes

For the following three, you DON'T need to run them now, but they may prove useful during the exercises.

To discover MAC addrs on each VM:

ifconfig eth0 | grep HWaddr

The main files for the NOX Python API are at:

/home/openflow/nox-0.2.1/src/nox/lib/core.py

A list of built-in functions in Python is at:

http://docs.python.org/lib/built-in-funcs.html

Part 1: Hub

Tutorial.py is set up as a hub. Run this first:

cd /home/openflow/nox-0.2.1/src
./nox_core -v -i ptcp:975 tutorial

Run secchan in the openflow1 VM xterm.

./secchan nl:0 tcp:10.0.2.2:975

Run tcpdump on end2 and end3

# On end2 VM  
tcpdump
# On end3 VM
tcpdump

Verify that you can ping from one host to another. From end1, ping end2 once:

ping 10.0.0.2 -c 1

Since this is a hub, the ICMP echo requests and replies from end1 will be seen by both end2 and end3. Now, take note of the average ping time with a longer sampling period:

ping 10.0.0.2 -i .1 -c 50

The hub is the slowest app, because all packets go to the controller, and packets are flooded out of every port.

Part 2: Learning Switch

In the file 'tutorial.py', you'll notice sections that say 'CODE GOES HERE'. Your challenge is to turn the hub into a simple learning switch. For every packet that arrives, the switch records the port for that MAC address. These MAC addresses should be stored in the 'inst.macs' variable, already created for you. Using the dest MAC addr, already extracted for you, write logic to learn MAC addresses and only forward packets to the port corresponding to that MAC address, rather that to the FLOOD virtual output port.

Example code to store a value in the mac table:

inst.macs[dstaddr] = port

Example code to check if a key exists in a dictionary:

if inst.macs.hask_key(dstaddr):

To verify your code, run tcpdump while doing ping tests. End3 should only see one packet from end1, at which point the controller learns the MAC address of end2 and end3 is shut off from seeing end1 to end2 ping traffic.

Part 3: Flow Switch

Now, you'll modify your learning switch from Part 2 to push flows into the switch directly, rather than processing all packets at the controller. We're using a software switch, but with no changes your code could run with a hardware-based OpenFlow switch and process flow entries at line rate.

Look near line 86 of pyswitch.py in the examples folder (/home/openflow/nox-0.2.1/src/nox/apps/examples/) for an example of how to push a flow into an OpenFlow switch. If you're not sure what goes in the 'actions' array, consult the OpenFlow spec, available at [openflowswitch.org/documents].

If your switch is in fact setting up flows, you should see dramatically reduced ping latencies, once the flow has been set up.

Part 4: Beyond

Congrats on getting a working flow switch! You might extend your switch with MAC timeouts, support for multiple switches (each with a different datapath ID), or counters for individual hosts or packet protocols.

Alternately, you could set up a software-based OpenFlow switch on a physical machine and try out your code, unchanged.