= 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: [[Image(Screenshot.png)]] 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 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 ^1^. 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 ^2^. 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/ 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/ deletedbsn@kvm-big:~$ }}} [[BR]][[BR]] ^1 Last time I played with IOS I remember you can do `run ` in order to run out-of-context commands. But, I'm not a CCNA so I might be lying.^ [[BR]] ^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.^