LINC-environment

Environment setup for FlowForwarding/LINC-Switch.

Table of Contents

1. Setup
2. Usage
3. Accessing the virtual machine
4. Developing LINC
5. Ping example
6. Mininet
7. Known issues

Setup

Below commands work on Ubuntu. If encounter an error while running vagrant up refer to known issues section.

1. Install Vagrant (tested with version 1.3.3):
   dpkg -i vagrant_<version>_<platform>.deb
2. Install Virtual Box:
   sudo apt-get install virtualbox
3. Install vagrant-bindler plugin (tested with version 0.1.4):
   vagrant plugin install bindler && vagrant bindler setup
4. Clone this repository:
   git clone https://github.com/FlowForwarding/LINC-Environment
5. Enter the cloned repository and install required plugins:
   cd LINC-environment && vagrant plugin bundle
6. Run vagrant to setup a machine for LINC development:
   vagrant up

After running the above steps you will end up with a virtual machine equipped with:

• Erlang,
• cloned LINC repository,
• Wireshark with OpenFlow 1.3 dissector installed,
• cloned LINC dependencies (optional),
• ping_example script generated in the home directory (optional),
• Mininet with support for LINC-Switch (optional).

Usage

Accessing the virtual machine

Username: vagrant
Password: vagrant

The virtual machine can be accessed via ssh or GUI provided by VirtualBox.

Logging in to the machine through ssh is very easy, you just have to type vagrant ssh in the project root directory. By default the VM has the X11 forwarding enabled so if you run Wireshark it's GUI will be forwarded to the hosts' UI. To change this behaviour and make the VM start with the UI, set the vb.gui option in Vagrantfile to true and uncomment the line #chef.add_recipe 'xfce4'. Then VirtualBox will display the UI in which you has to log in and start Xfce4 issuing startx.

Developing LINC

After booting the machine the LINC code is cloned to /home/vagrant/development/linc. By default also LINC dependencies are cloned and you can find them in /home/vagrant/development/linc-deps. The entire /home/vagrant/development directory is shared with your host in development under project root directory. Thanks to that you can use your own editor to edit files.

Ping example

By default the machine will have a script ping_example in the /home/vagrant directory. This script allows you to run simple example presenting LINC-Switch and the OpenFlow controller operation. While running the example you can observe OpenFlow protocol messages between the switch and the controller and it can serve as a starting point for writing more complex examples.

To run the example follow these steps:

1. Run ~/ping_example setup to compile the code, configure two tap interfaces and generate switch configuration for one logical switch connecting to these two interfaces.
2. Run ~/ping_example wireshark to start three instances of Wireshark capturing on tap0, tap1 and loopback.
3. Enter display filter of13.ofp_header in the Wireshark capturing on the loopback (lo) interface to see only OpenFlow protocol messages.
4. Run ~/ping_example switch to start the switch.
5. Run ~/ping_example controller (in another console); you will observe OpenFlow messages exchange related with establishing the connection.
6. Run ~/ping_example ping to send prepared ping message through the tap0; you will observe switch sending the PacketIn message to the controller enclosing the packet generated by the ping and then controller sending the PacketOut message that will cause the switch flood the packet on rest interfaces - only the tap1 in this case. The switch and controller are started in the debug mode so you should also see appropriate messages on their consoles.
7. To stop the example close the switch's and controller's consoles (Ctrl+g q) and run ~/ping_example teardown.

The ping_example setup and ping_example teardown commands overwrite files in /home/vagrant/development/linc.

Mininet

Mininet is a tool facilitating creation of realistic virtual networks. More you can find on Mininet official website.

The VM has Mininet on board installed in /home/vagrant/test-env/mininet directory. You can use it to setup testing environments for LINC-Switch. All Mininet dependencies and installation of LINC-Switch sit in /home/vagrant/test-env.

To get started using Mininet with LINC-Switch see the tutorial. Note that you should omit the Installation section.

Known issues

SSH connection problem on MAC OS

When running Vagrant with VirtualBox on Mac OS it sometimes cannot connect to a running VM by issuing vagrant up reporting following error:

The SSH connection was unexpectedly closed by the remote end. This usually indicates that SSH within the guest machine was unable to properly start up. Please boot the VM in GUI mode to check whether it is booting properly

A workaround is to generate ssh config that will allow you to connect to the VM by using ssh directly. To achieve this follow the steps below:

1. Generate ssh config from vagrant and put it into the ssh config file: vagrant ssh-config >> ~/.ssh/config
2. By default vagrant set the Host option to default. Edit the ssh config file and change default to whatever you want. For example linc-dev.
3. Now you can connect to the running VM using ssh directly: ssh linc-dev

SSH connection unexpectedly closed

Sometimes after running vagrant up you may got the error:

The SSH connection was unexpectedly closed by the remote end. This usually indicates that SSH within the guest machine was unable to properly start up. Please boot the VM in GUI mode to check whether it is booting properly.

To remedy this situation just issue vagrant reload.