.. _selena_installation:

Installation
============

SELENA installation is simple and straightforward. In this section we present
the installation of the platform on an Ubuntu 14.04 host, but this approach can
equally apply on debian-based distributions with recent package versions.

XEN and XAPI
-------------

Most recent Ubuntu version currently provide pre-packaged XEN hypervisor
support. In Ubuntu, XEN can be installed by running the following commands::

    sudo apt-get install xen-hypervisor-4.4-amd64 openvswitch-switch quemu-common

Because SELENA requires hypervisor modifications, users must
patch the Hypervisor source code. In order to modify the source
code and install the modified Hypervisor in Dom0 you need
to issue the following commands on a terminal::

    cd ~
    git clone git://github.com/selena-project/selena-xen.git
    sudo apt-get source xen-hypervisor-4.4-amd64
    cd xen-4.4.0/
    patch -p2 < ../selena-xen/xen_tdf/xen-4.3.tdf.patch

    sudo apt-get build-dep xen-hypervisor-4.4-amd64
    sudo dpkg-source --commit
    sudo dpkg-buildpackage
    sudo dpkg 

Furthermore, SELENA requires the XAPI toolstack for the experiment automation
API. Unfortunately, when we were writting these instructions XAPI packages were
removed from the Ubuntu and Debian repositories due to a series of `build bugs
<https://bugs.debian.org/740517>`_. In order to build all required
packages, the XAPI team provides an experimental script, which can run
by following the commands::

    cd ~
    git clone  git://github.com/xenserver/buildroot.git
    cd buildroot/
    make
    make install 
    sudo xenserver-install-wizard
    echo 'openvsiwtch' > /etc/xcp-networkd.conf
    echo 'openvsiwtch' > /etc/xapi/xcp-networkd.conf


Unfortunately, the previous installation doesn't enable all XAPI services
at boot time. You can enable relevant services manually:: 

    sudo /etc/init.d/xcp-networkd start
    sudo /etc/init.d/xcp-rrdd start
    sudo /etc/init.d/forkexecd start
    sudo /etc/init.d/squeezed start
    sudo /etc/init.d/message-switch start
    sudo /etc/init.d/xenopsd-xenlight start
    sudo /etc/init.d/xenopsd-xc start
    sudo /etc/init.d/xapi start

or you can enable the services to start at boot time::

    sudo update-rc.d xcp-networkd defaults 
    sudo update-rc.d xcp-rrdd defaults 
    sudo update-rc.d forkexecd defaults 
    sudo update-rc.d squeezed defaults 
    sudo update-rc.d message-switch defaults 
    sudo update-rc.d xenopsd-xenlight defaults 
    sudo update-rc.d xenopsd-xc defaults 
    sudo update-rc.d xapi defaults 

In addition to the previous configuration settings, XEN requires the
configuration of a storage location for VM disks. By default, the XEN
installation will uses iso files located in /usr/share/xapi/packages/iso.
In order to configure a separate partition, you must run the following
commands::
      
    mkfs.ext4 /dev/sdb1
    export SRDEVICE=/dev/sdb1
    . /etc/xcp/inventory
    SR=$(xe sr-create host-uuid=$INSTALLATION_UUID type=ext name-label='Local storage' device-config:device=$SRDEVICE)
    POOL=$(xe pool-list --minimal)
    xe pool-param-set uuid=$POOL default-SR=$SR
..    /etc/xcp/inventory
..    sudo apt-get install lvm2
..    sudo pvcreate /dev/sdb
..    sudo vgcreate vm_storage /dev/sdb

SELENA python library
---------------------

In order to install SELENA python control library you need to simply execute
the setup script provided with the source code. Specifically,::

    git clone git://github.com/selena-project/selena-control.git
    cd ~/selena-control/
    python setup.py install

The python library is fully compatible with the pip packaging system, which
can be used to remove the library.

In addition, along with the python library, the SELENA project provides a
series of minimal guest templates, which must be installed on the local server
setup. Available templates can be found `here
<https://drive.google.com/folderview?id=0Byi7sMTL0nJiM2lIcG85QnRZR0E>`_. In
order to import the VM templates, users must use the following command::

     sudo xe vm-import sr-uuid=$SR filename=templatename.xva

In addition, the users must maintain custom Linux kernel images in the Dom0
filesystem under /root/guest/. The relevant images can be found also here `here
<https://drive.google.com/folderview?id=0Byi7sMTL0nJiM2lIcG85QnRZR0E>`_.

Time Dilation control
---------------------

In order to control the time dilation factor of the XEN hypervisor a user must
update the TDF constant in the header file
``xen-4.4.0/xen/include/asm-x86/config.h``, recompile the source file using the
provided Makefile and replace the hypervisor binary under the /boot/ directory
with the one generated by the compilation. 

Importing custom guest templates in SELENA
------------------------------------------

SELENA provides a set of minimal guest templates which can be used to replicate
a wide range of network experiments. In order to install the relevant VM in a 
XEN installation, the user much follow the steps bellow: ::
    
    cd ~
    git clone https://github.com/selena-project/selena-guests.git
    sh ~/selena-guests/selena-guest-download.sh

Nonetheless, if users require to incorporate custom VM templates in an
experiment, the platform has a minimal requirement to run a low-overhead python
service, which is used to control remotely the guest. In order to install the
service, the user must run the following commands::

    cd ~
    git clone http://github.com/selena-project/selena-agent.git
    cp ~/selena-agent/init.d_script/selena /etc/init.d/selena
    mkdir -p /root/bin/scripts/
    cp -r ~/selena-agent/root_bin_scripts/*  /root/bin/scripts/ 
    update-rc.d selena defaults