The Big Switch Controller

This page describes the controller by Big Switch Networks. The controller uses a REST API that leverages HTTP control messages to let an admin manipulate flows.

Installation/Setup

The controller may be reached from ofc, accessible as user native, password native101 from orbit-lab.org. The controller is a KVM guest currently named bigswitchcontroller-110405. You can confirm this through virsh or virt-manager. The latter is a GUI, and more straight forward.

The default user is admin. The controller will then ask you for a password and network configurations. The password has been set to native101, and the following used for the network setup:

• IP address: 172.16.0.14
• netmask: 255.255.0.0
• gateway: 172.16.0.1
• nameserver: 172.16.0.9
• domain: orbit-lab.org

You can see this clearly in the screenshot below, taken from an actual setup session:

once configured, you should be able to ssh to it from the outside.

I BigOS CLI

This is the main interface to the Big Switch controller. From here, you can query for / set various OpenFlow-related parameters such as controller state and the switches connected to it.

1.1 Logging in

From gw.orbit-lab.org, ssh to kvm-big as user admin, password native101. You should see something like below:

~$ ssh kvm-big -l admin
admin@kvm-big's password: 
Last login: Sat Feb 12 07:19:47 2011 from 10.50.0.12
BigShell (bigsh) v0.1 (c) by Big Switch Networks.
default controller is: 127.0.0.1:8000
172.16.0.14> 

1.2 Information Lookup

The caret is the prompt for the CLI, which follows syntax similar to Cisco IOS. To see available commands, just type "?" or hit tab. As with regular switch CLIs, the controller understands command completion. For example, to see the list of OpenFlow switches connected to the controller, type show switch:

172.16.0.14> show switch
Switch DPID             Active Last Connect Time   IP Address   Socket Address      Max Packets Max Tables
-----------------------|------|-------------------|------------|-------------------|-----------|----------
00:00:00:00:00:00:00:01 True   2011-02-14 02:25:53 172.16.0.241 /172.16.0.241:52683 256         3         
00:00:00:10:10:20:32:30 False  2011-02-09 07:36:59 172.16.0.253 /172.16.0.253:63202 256         2         
00:00:00:10:10:22:32:32 True   2011-02-14 02:25:30 172.16.0.253 /172.16.0.253:62957 256         2         
00:00:00:10:10:24:32:34 True   2011-02-10 15:56:57 172.16.0.4   /172.16.0.4:59345   256         2  

More information on each switch can be found by context switch to the DPID's of the switches:

172.16.0.14> show switch 00:00:00:10:10:22:32:32 desc
Serial # Vendor          Make                       Model    SW Version
--------|---------------|--------------------------|--------|----------
None     NEC Corporation Reference Userspace Switch sw-sb-01           

Here, we have switched to the context of a switch whose DPID is 00:00:00:10:10:22:32:32, in order to look up general information about it.

1.3 Monitoring VSIs

• show switch [dpid] flow shows you the current active flows on a switch of DPID [dpid].
• show switch [dpid] trace [opt] shows you the OpenFlow control messages associated with that switch. Optional parameters may be added to the command.

1.4 Configuration

Configuration of the controller-managed OpenFlow network is done from the configuration prompt. To enter the prompt, first enter enabled mode (via command enable) and then enter configuration mode via configure.

kvm-big> en
kvm-big# config
kvm-big(config)# 

As with IOS, various contexts exist for the various configurable elements. For example, to configure a switch, you would enter a particular switch's context:

kvm-big(config)# switch 00:00:00:10:10:25:32:35
kvm-big(config-switch)#

Where the colon-and-hex value is the switch's DPID. Issuing a config command for a nonexistent element (e.g. switch DPID or a flow) would create a new OpenFlow element. Also, unlike in the case of IOS, regular mode commands may be run from here unmodified ¹. All available parameters for a certain context can, again, be found by hitting tab or with ?.

II The REST API

In addition to the CLI, a scripting-friendly REST API is available through debug mode. This is a separate process form the CLI.

Flow manipulation from the API is done by issuing HTTP control messages (e.g. PUT, GET, DELETE) using curl. The API will respond with JSON format data. Here we'll describe how to use the REST API through an example based on the REST documents (linked at the bottom of the page) and e-mail exchanges.

2.1 Logging in, some prep work

1. Enter debug mode. In order to use the REST API, you must be at the Linux shell. Type "debug bash" to switch out of the CLI.

   172.16.0.14> debug bash
   
   ***** Warning: this is a debug command - use caution! *****
   ***** Type "exit" or Ctrl-D to return to the BigOS CLI *****
   
   bsn@bigswitchcontroller:~$ 
   

2. open port 8000. Allow connections to port 8000 with the command sudo ufw allow 8000. You'll be using this port to talk to the controller using curl.

2.2 Using curl

curl is a data transfer tool supporting a menagerie of protocols including HTTP. FTP, SCP, and the likes. It allows both pushing and pulling of data to/from a server. In our case, curl allows us to manipulate the controller through HTTP without worrying about the details of the protocol.

2.2.1 HTTP queries

Underneath, HTTP GET messages are used to query the controller. Superficially, the syntax is:

curl [-v] http://localhost:8000/rest/parameter/

Where parameter is switch, controller-node, and other OpenFlow network elements. the -v flag sets the session to debug mode, in which you see the HTTP chatter that goes on in the back. For example, to pull information about the current controller:

bsn@kvm-big:~$ curl http://localhost:8000/rest/controller-node/
[{"active": true, "last-startup": "2011-04-19 00:59:07.725000", "listen-address": "10.0.2.15", "listen-
port": 6633, "id": "10.0.2.15:6633"}]bsn@kvm-big:~$ 

The things between the square brackets is the actual data; the prompt gets concatenated to the output, which is somewhat awkward but doesn't cause any issues.

Some query contexts may have multiple results, e.g. for switch, which lists all OpenFlow switches the controller is aware of:

bsn@kvm-big:~$ curl http://localhost:8000/rest/switch/
[{"tables": 3, "socket-address": "/172.16.0.241:35080", "dpid": "00:00:00:00:00:00:00:01", "capabilities": 
71, "controller": "172.16.0.14:6633", "actions": 2049, "ip-address": "172.16.0.241", "connected-since": 
"2011-05-13 18:21:21.141000", "active": true, "buffers": 256}, {"tables": 2, "socket-address": 
"/172.16.0.253:62310", "dpid": "00:00:00:00:08:21:56:9d", "capabilities": 199, "controller": 
"172.16.0.14:6633", "actions": 4095, "ip-address": "172.16.0.253", "connected-since": "2011-05-15
01:23:13.030000", "active": false, "buffers": 256}, {"tables": 3, "socket-address": "/172.16.20.1:45364", 
"dpid": "00:00:00:10:10:00:80:01", "capabilities": 71, "controller": "172.16.0.14:6633", "actions": 2063, 
"ip-address": "172.16.20.1", "connected-since": "2011-05-08 17:52:31.214000", "active": false, "buffers": 
256}, {"tables": 2, "socket-address": "/172.16.0.253:62301", "dpid": "00:00:00:10:10:22:32:32", 
"capabilities": 199, "controller": "172.16.0.14:6633", "actions": 4095, "ip-address": "172.16.0.253", 
"connected-since": "2011-05-15 18:10:25.891000", "active": true, "buffers": 256}, {"tables": 2, "socket-
address": "/172.16.0.253:62302", "dpid": "00:00:00:10:10:25:32:35", "capabilities": 199, "controller": 
"172.16.0.14:6633", "actions": 4095, "ip-address": "172.16.0.253", "connected-since": "2011-05-15 
18:10:25.886000", "active": true, "buffers": 256}, {"tables": 3, "socket-address": "/172.16.20.1:49217", 
"dpid": "00:00:00:23:20:21:f8:4d", "capabilities": 71, "controller": "172.16.0.14:6633", "actions": 2063, 
"ip-address": "172.16.20.1", "connected-since": "2011-05-08 17:33:43.433000", "active": false, "buffers": 
256}]bsn@kvm-big:~$

For such cases, information about each element is separated by curly braces. To pull information about just one switch, for example, you can query for something "one directory down":

bsn@kvm-big:~$ curl http://localhost:8000/rest/switch/00:00:00:10:10:25:32:35/ 
{"tables": 2, "socket-address": "/172.16.0.253:62302", "dpid": "00:00:00:10:10:25:32:35", "capabilities":
199, "controller": "172.16.0.14:6633", "actions": 4095, "ip-address": "172.16.0.253", "connected-since":
"2011-05-15 18:10:25.886000", "active": true, "buffers": 256}

2.2.2 Modifying flows (HTTP PUT/DELETE)

Pushing flows

HTTP PUT messages are used to modify flows. The basic syntax is as follows:

curl -X PUT -d '{"config-params"}' http://localhost:8000/rest/parameter-to-change/

where config-params is in JSON format and the options based on dpctl parameters ². For example, to create a flow named "testflow" which redirects pings from address 10.18.1.1 to port 0/29 on switch of DPID 00:00:00:10:10:25:32:35:

bsn@kvm-big:~$ curl -X PUT -d '{"name":"testflow","active":"True","src-ip":"10.18.1.1","ether-type":"2048",
"switch":"00:00:00:10:10:25:32:35","actions":"output=29"}' http://localhost:8000/rest/flow-entry/ <hit enter>
savedbsn@kvm-big:~$ 

And sure enough, if you check back with the CLI:

kvm-big> sh run
 ...

!
switch 00:00:00:10:10:25:32:35
  flow-entry testflow
    active True
    ether-type 2048
    src-ip 10.18.1.1
    actions output=29
!

...

Removing flows

Deleting the flow utilizes the DELETE message:

curl -X http://localhost:8000/rest/parameter-to-delete/

Removing our flow above, therefore, requires this command:

bsn@kvm-big:~$ curl -X DELETE http://localhost:8000/rest/flow-entry/testflow/  <hit enter>
deletedbsn@kvm-big:~$ 

^{1 Last time I played with IOS I remember you can do run <full command> in order to run out-of-context commands. But, I'm not a CCNA so I might be lying.
2 man dpctl on a machine running a controller should give you the man pages describing the syntax. will possibly add links to an on-line man page here in the future.}