Tutorial of installing ClickOS testbed

This tutorial provides a step-by-step guide to setup a virtual machine (VM) that runs ClickOS and a simple demonstration of testing ClickOS.
All commands proceeding with '#' are run as root privilege. (type sudo su - to switch to root)

1. Download VM image and install VirtualBox

We provide a virtual machine image with Ubuntu 14.04.4 (LTS) 64-bit installed. You can download the image from here and use it as a start point. VirtualBox is required to open the VM image.
Username: osboxes
Password: osboxes.org

2. Configure the VM

Set memory to 1024MB
Set the number of processors to 2.

3. Install Xen

Xen is one of the most popular virtualized platforms. In this project, we are going to use Xen to support our Network Function Virtualization (NFV).

Install dependencies for Xen:

# apt-get update
# apt-get install build-essential wget
# apt-get install bcc bin86 gawk bridge-utils iproute libcurl3 libcurl4-openssl-dev bzip2 module-init-tools transfig tgif 
# apt-get install texinfo texlive-latex-base texlive-latex-recommended 
# apt-get install texlive-fonts-extra texlive-fonts-recommended pciutils-dev mercurial
# apt-get install make gcc libc6-dev zlib1g-dev python python-dev python-twisted 
# apt-get install libncurses5-dev patch libsdl-dev libjpeg62-dev
# apt-get install libvncserver-dev
# apt-get install iasl libbz2-dev e2fslibs-dev git-core uuid-dev ocaml ocaml-findlib 
# apt-get install libx11-dev bison flex xz-utils libyajl-dev
# apt-get install gettext libpixman-1-dev
# apt-get build-dep xen
# apt-get install libglib2.0-dev 
# apt-get install libyajl-dev

Make a directory called tutorial:
```
# mkdir tutorial
```

Download Xen-4.4.1 in the tutorial directory:

# cd tutorial
# wget http://people.cs.clemson.edu/~hongdal/xen-4.4.1.tar.gz
# tar -xf xen-4.4.1.tar.gz

Compile and build Xen:

# export XEN_ROOT=`pwd`/xen-4.4.1
# cd $XEN_ROOT
# ./configure
# make world
# make install

Configure your system to boot from Xen:
Before doing this, it is highly recommended you taking a snapshot of the VM. Don't worry about those warnings when executing update-rc.d commnads.
```
# /sbin/ldconfig
# update-rc.d xencommons defaults 19 18
# update-rc.d xendomains defaults 21 20 
# update-rc.d xen-watchdog defaults 22 23
```
Update some of the configuration lines at /etc/default/grub to the appropriate values:

GRUB_DEFAULT=3
GRUB_HIDDEN_TIMEOUT=0

Update grub and reboot the system:
There may be some error messages during the system booting. Don't worry about that. It may take a few minutes to reboot from Xen. Please wait until the login interface shows up.
```
# update-grub
# reboot
```
Verify Xen has been installed successfully:
After rebooting, the system starts a graphic user interface (GUI) automatically. However, the virtual machine does not support GUI in Xen. So you need to switch to a command line interface (CLI). Press control + alt + F1 to switch to a CLI. input your username and password to log in. After logging in, switch to root privilege.
Use the following command to verify Xen has been installed successfully:
```
# xl list
```
Example outputs of xl list:
```
Name                                        ID   Mem VCPUs  State   Time(s)
Domain-0                                     0  4098    32     r-----   23926.7
```

4. Build ClickOS

To learn more about ClickOS, refer to http://cnp.neclab.eu/clickos.

Get source codes:
Download clickos codes into the tutorial directory.

# cd tutorial
# wget http://people.cs.clemson.edu/~hongdal/clickos.tar
# wget http://people.cs.clemson.edu/~hongdal/mini-os.tar
# wget http://people.cs.clemson.edu/~hongdal/cosmos.tar
# wget http://people.cs.clemson.edu/~hongdal/toolchain.tar
# tar -xf clickos.tar
# tar -xf mini-os.tar
# tar -xf cosmos.tar
# tar -xf toolchain.tar

Set environment vairables:
Before executing the following commands, make sure pwd outputs the path of your tutorial/ direcotry. E.g., its output will look like: /root/tutorial. These variables are important in building the ClickOS.
Each time you reboot the system or switch to another user, you should check whether these variables are intact, by typing echo $VARIABLE-NAME. E.g., echo $XEN_ROOT to check variable $XEN_ROOT
```
# export XEN_ROOT=$(pwd)"/xen-4.4.1/" 
# export MINIOS_ROOT=$XEN_ROOT"extras/mini-os/" 
# export CLICKOS_ROOT=$(pwd)"/clickos/"
# export TOOLCHAIN_ROOT=$(pwd)"/toolchain/"
# export COSMOS_ROOT=$(pwd)"/cosmos/"
```
Replace mini-os:
MiniOS is an operating system that comes with Xen. ClickOS is built based on MiniOS. Here we need to replace Xen's mini-os with ClickOS's minios.
```
# rm -rf $MINIOS_ROOT
# cp -rf $(pwd)"/mini-os/" $MINIOS_ROOT
```

Build toolchain:
This toolchain is for ClickOS's C++ library.

# cd $TOOLCHAIN_ROOT
# make
# export NEWLIB_ROOT=$TOOLCHAIN_ROOT"/x86_64-root/x86_64-xen-elf"
# export LWIP_ROOT=$TOOLCHAIN_ROOT"/x86_64-root/x86_64-xen-elf"

Build ClickOS kernel:

# cd $CLICKOS_ROOT
# ./configure --enable-minios --with-xen=$XEN_ROOT --with-minios=$MINIOS_ROOT
# make minios

Build cosmos:
cosmos is a tool used for booting ClickOS kernel.

# cd $XEN_ROOT
# cd tools
# make -C include
# cd $COSMOS_ROOT
# make DOMLIB=xl

Set the PATH environment variable:

# export PATH=$PATH":/$COSMOS_ROOT/dist/bin"

5. Install Open vSwitch:

ClickOS should work with Linux bridge, VALE bridge, Open vSwitch, and many other software switches.
We are going to use Open vSwitch (OVS) as the software switch.

Install OVS:

# cd tutorial
# wget http://openvswitch.org/releases/openvswitch-2.5.0.tar.gz
# tar -xf openvswitch-2.5.0.tar.gz
# cd openvswitch-2.5.0/
# ./configure --with-linux=/lib/modules/`uname -r`/build
# make 
# make install
# make modules_install

Configure and run OVS:
Each time the system is rebooted, you need to repeat these commands to reconfigure OVS.
The following commands will be executed in the directory: tutorial/openvswitch-2.5.0/

# /sbin/modprobe openvswitch
# mkdir -p /usr/local/etc/openvswitch
# ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
# 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

Create a bridge on OVS:

# ovs-vsctl add-br ovs-lan

Use ovs-vsctl show to verify that OVS is running correctly. Example outputs:

e6d82000-68d3-49cc-a5d0-3e51508ad772
    Bridge ovs-lan
        Port ovs-lan
            Interface ovs-lan
                type: internal

6. Start a ClickOS instance

Create configuration file for Xen:
Change your working directory to tutorial/clickos/minios. We will use an existing Xen configuration file. Update some of the values in config.xen:
```
kernel = './build/clickos_x86_64'
vcpus = '1'
vif = ['script=vif-openvswitch,mac=00:00:00:00:01:00,bridge=ovs-lan']
name = 'click0'
```
Delete this line in config.xen, since it may cuase some problem:
```
cpus = '2'
```
Create configuration file for Click:
The Click configuration file describes the functionality that a ClickOS instance will implement. As a simple test, the following scripts describe a simple network function that receives packets from the network interface, prints the packets, and sends the packets back to the network:
```
FromDevice -> Print('OK') -> EtherMirror -> ToDevice
```
Save the script as a file, mirror.click.
Click is a scripting language that can define network functions based on Click Modular. To write more complicated network functions using Click, refer to the Click Element website. Some examples could be found here.
Start ClickOS instance:
We will use cosmos to start a ClickOS instance. Check whether $COSMOS_ROOT is intact by typing echo $COSMOS_ROOT and set it appropriately.
```
# xl create config.xen
# $COSMOS_ROOT/dist/bin/cosmos start click0 mirror.click
```
To verify that the ClickOS instance is running, type xl list. You should see something like:
```
Name                                        ID   Mem VCPUs  State   Time(s)
Domain-0                                     0  4098    32     r-----   23926.7
click0                                       1    12     1     r-----     234.5 
```
It's importantant to make sure the State of click0 is r-----.
To watch the output of click0, type xl console click0. To quit the console, press control + ]
Example outputs:

7. Exercise

ICMP Responder
Use the following script as a template to create a Click configuration file, icmp.click. Set the IP and MAC addresses appropriately and make your name being printed:

    // define the IP address of this network function. 
    // This IP must NOT be the same with your VM's IP.
    define($IP 192.168.1.2);    
    // This MAC must be identical with the one you defined in config.xen
    define($MAC 00:00:00:00:01:00);

    source :: FromDevice;
    sink   :: ToDevice;
    c :: Classifier(
        12/0806 20/0001, 
        12/0806 20/0002, 
        12/0800, 
        -); 

    arpq :: ARPQuerier($IP, $MAC);
    arpr :: ARPResponder($IP $MAC);  // No comma here. 

    source -> c;
    c[0] -> ARPPrint -> arpr -> sink;
    c[1] -> [1]arpq;
    Idle -> [0]arpq;
    arpq -> ARPPrint -> sink;
    c[2] -> CheckIPHeader(14) -> ICMPPingResponder() -> Print('Responder') -> EtherMirror() -> sink;
    c[3] -> Discard;

Kill existing ClickOS instances by xl destroy click0. Then start a new instance:

# xl create config.xen
# $COSMOS_ROOT/dist/bin/cosmos start click0 icmp.click

Add your VM's network interface (assuming it's eth0, with IP, 192.168.1.1) to OVS so that you can ping the ClickOS instance from your VM:

# ifconfig eth0 0
# ovs-vsctl add-port ovs-lan eth0
# ifconfig ovs-lan 192.168.1.1 netmask 255.255.255.0 up

Now ping the ClickOS instance from your VM.

# ping 192.168.1.2

You should observe responds from the ClickOS.
To watch the outputs of the ClickOS instance:

# xl console click0

8. Submission

The submission of this project is similar to Project 3.
Students should include screenshots in their reports to indicate that each task has been completed.
Specifically, for the exercise, students should modify the given template configuration file to make their own names printed.

Wiki

clickos-setup / Tutorial of installing ClickOS testbed