The SOS agent code was implemented by Aaron Rosen – a past Masters student and member of our group. General instructions for the installation of the agent code can be found on Aaron's GitHub page, but are summarized and clarified here. Please do not follow the instructions on Aaron's page, since we have modified the project since then. The agent code will still be sourced from his repository though.

Installing the Agent Software

To install the agent code, download it from GitHub:

$ git clone http://github.com/aaronoroson/SteroidOpenFlowService.git
$ cd SteroidOpenFlowService
$ git submodule init
$ git submodule update
$ cd sos-agent
$ sudo apt-get install clang uuid-dev libxml2-dev -y
$ make

Installing Open vSwitch

At this point, the agent code has been compiled and is ready to go. Before we can use it with the controller, we need to also install Open vSwitch (OVS) on the agent machine. The purpose of OVS is to perform packet header rewrite operations not currently possible on hardware switches.

Complete OVS installation instructions, including the installation of any prerequisite packages are available here. Installation is typically accomplished on Linux by running the following set of commands:

$ sudo apt-get install pkg-config autoconf automake linux-libc-dev libtool libssl-dev linux-headers-`uname -r` -y
$ sudo wget http://openvswitch.org/releases/openvswitch-2.3.2.tar.gz
$ sudo tar -xvzf openvswitch-2.3.2.tar.gz
$ cd openvswitch-2.3.2
$ ./boot.sh
$ ./configure --with-linux=/lib/modules/`uname -r`/build
$ make
$ sudo make install
$ sudo make modules_install
$ sudo modprobe openvswitch
$ sudo mkdir -p /usr/local/etc/openvswitch/
$ sudo ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema

Running Open vSwitch

The following will need to be started in order to use OVS:

$ ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
  --remote=db:Open_vSwitch,Open_vSwitch,manager_options \
  --private-key=db:Open_vSwitch,SSL,private_key \
  --certificate=db:Open_vSwitch,SSL,certificate \
  --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \
  --pidfile --detach
$ ovs-vsctl --no-wait init
$ ovs-vswitchd --pidfile --detach

These should always be run prior to attempting to use OVS. Without these prerequisite commands, OVS will likely report an error stating something along the lines of "unable to connect to database."

Configuring the Open vSwitch Bridge

The agent code running on the agent machine will communicate with devices on the data plane via an OVS bridge. This will allow us to exert control over the packets traversing to and from the agent. We can use OVS's virtual switch control program to instantiate a bridge:

$ sudo ovs-vsctl add-br br_ovs

where br_ovs is the name of the bridge (which we will also use throughout these instructions). You can name this whatever you want as long as it does not conflict with any interfaces listed in ifconfig.

Then, we can add ports to the bridge:

$ sudo ovs-vsctl add-port br_ovs ethX

where ethX is the interface on the agent machine leading to the data plane. ethX is just a placeholder in this instruction, which should be swapped for the valid data plane interface name in ifconfig.

	Be careful to not accidentally add your control interface to the bridge – you might lock yourself out of the machine if using SSH.

Then, we can set the DPID of the OVS bridge to something that's easier to remember. This is not required; however, it makes it easier to reason with the topology and to debug if necessary. Note that this same DPID should be used when configuring the controller with this agent bridge.

$ ovs-vsctl set bridge br_ovs other-config:datapath-id=0011223344556677

Next, we need to tell the OVS bridge to not allow any packets through the switch if it's not connected to the controller:

$ sudo ovs-vsctl set-fail-mode br_ovs secure

After that, the OVS bridge needs to be connected to the controller:

$ sudo ovs-vsctl set-controller br_ovs tcp:<your-controller-ip>:6653

where <your-controller-ip> is the IP address of the SOS-enabled Floodlight controller you are running or will run. The default port of 6653 is used; however, if desired, you can change the port both here and on the controller as long as you do it consistently.

Finally, we need to route packets through our new OVS bridge instead of the old ethX data plane interface. This can be accomplished by removing the IP address and route from ethX and adding it instead to br_ovs:

$ sudo ifconfig ethX 0
$ sudo ifconfig br_ovs <your-desired-ip>/<your-desired-CIDR-mask> up

where <your-desired-ip> is the IP address you want the agent machine's data plane interface to have, and where <your-desired-CIDR-mask> is the CIDR subnet mask you would like to use as your data plane subnet. For example, a valid IP and netmask might look like 10.0.0.1/24.

As a double-check, you can check the routes to verify the OVS bridge is now being used to route traffic into and out of the data plane:

$ sudo route -n

Running the Agent Software

After all the prior steps are complete, the agent code is ready to run! Running it is very straightforward:

$ ./<agent-clone-directory>/SteroidOpenFlowService/sos-agent/run.sh

where <agent-clone-directory> is the directory in which you cloned the agent repository from GitHub.

As SOS is running and receiving SOS connections to optimize, you should see information appear in stdout of the agent.