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.

Contents

• Installation/Setup
• BigOS CLI
• REST API

I 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.

II 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.

2.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> 

2.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.

2.3 Monitoring VSI OpenFlow Stats

• 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.

2.4 Context switching

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. exit leaves a context without saving any of the changes made; you may make configurations persistent with write memory.

Also, unlike in the case of IOS, regular mode commands (e.g. show) can be run from the config prompt unmodified ¹. All available parameters for a certain context can, again, be found by hitting tab or with ?.

2.5 Adding/Removing static flow entries

Flows for switches may be manually added by entering the flow-entry [flowname] context from the context of a switch you want to push flows to. A new [flowname] parameter will create and enter a new context for a flow named [flowname]. Some important things to note about flow-entries are:

• By default they are disabled (active False). Enable a flow entry from its context with active True (note that 'True' and 'False' must be capitalized)
• ether-type must be specified in decimal (e.g. 2048, not 0x0800 for IP)
• src-ip may be a single IP address or an IP block (e.g. 192.168.1.0/24).
• protocol refers to the IP header protocol field (e.g. 1 for ICMP)

2.5.1. declaring actions

the actions parameter of a flow-entry loosely follow the dpctl syntax; notably, the output option takes parameters with an equals ( sign, not a colon. Several things to note are:

• output= may only be followed by one value. If more than one port is to be specified, the declaration will be:

  kvm-big(config-flow-entry)# actions output=x,output=y,...  
  

• If an action does not seem to work (e.g. flood), it may need to be perpended with output=.

III 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.

3.1 Logging in and initial setup

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.

3.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.

3.2.1 Getting information (HTTP GET)

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}

3.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.}