.. Copyright (c) 2018  University of Houston

.. raw:: latex

  \newpage

Experiment Quickstart
=====================

There is detailed documentation of all of the options available for each script available later this this
documentation.  This section is a quick example of how to run the basic experiment with minimal non-default
parameters (and limited explanation).

Install Tools
-------------

You will need to install a number of python libraries - if you are not using a virtualenv you may have to use
``sudo`` with ``pip``::

  $ pip install --upgrade requests lxml cryptography ipaddress paramiko matplotlib

You will need a working `geni-lib` installation set up with your GENI credentials.  You can find installation
instructions in the `online geni-lib documentation <http://geni-lib.readthedocs.io/en/latest/index.html>`_.

You will also need to clone and install a pair of libraries provided by the UH NetLab::

  $ hg clone https://bitbucket.org/uh-netlab/uhgeni
  $ hg clone https://bitbucket.org/uh-netlab/uhexp

  $ cd uhgeni; pip install .; cd ..
  $ cd uhexp; pip install .; cd ..

Finally, we will clone the repository containing the tools to build the experiments::

  $ hg clone https://bitbucket.org/uh-netlab/doe-nf
  $ cd doe-nf

Run Experiment
--------------

In order to run the experiment you need to choose a VTS site to use with ``scripts/reserve.py`` - we'll use
the site located at GPO for this example, but you can choose any publicly-available VTS site.  Once you
have chosen a site you will need to link a Dropbox account with your user credential at that site, in order
to transfer data for analysis out of your isolated topology, as VTS topologies do not have access to the internet.
You can find instructions for this in the `online GENI VTS documentation <http://geni-vts.readthedocs.io/en/latest/howtos/dropboxassoc.html>`_.
The experiment will still function without this feature, but you will not be able to easily retrieve data for analysis.

When you are ready to execute the experiment, you will make a reservation and then use the reserved topology details 
to invoke the experiment orchestration script (replace ``myslicename`` with a slice you have created)::

  $ scripts/reserve.py --delete --slice myslicename --site vts-gpo --num-sites 2 --num-sensors 2 --with-nf --mgmt-delay 1000 --mgmt-reorder 20

This will create a topology with two sensor sites that have two sensors each, 1000ms of delay (typical of
geosynchronous satellite transport), 20% packet reordering, and employ the NF in the topology.  It
will also delete any previously existing sliver at this site if one exists.  Once this returns it will have saved
the manifest, request rspec, and `dot` file representing your reservation in the current directory.  You can now
run the actual experiment::

  $ scripts/runexp.py --sites 2 --sensors 2 --sensor-rate 25 --run-time 30

You will be asked for the passphrase for any SSH private keys needed to execute the experiment.  After setting up
all the nodes in the topology this will run the sensors for 30 seconds and then shut everything down.  You can view
the current progress by tailing the live output log in another terminal::

  $ tail -F doe-exp.log


Generate Charts
---------------

If you have enabled Dropbox syncing with the VTS site, your runtime data will appear in your dropbox in
``Apps/vts-gpo/<sliver-uuid>`` as the experiment run ends.

If your Dropbox folder is not accessible from the place where you installed the analysis tools, you will need
to copy ``nf2/nf2/_host_root/nf-eth1-eth2.log`` to an accessible location.  You can generate a standard set of
charts using the following command::

  $ scripts/nflogalyze.py --logs /path/to/nf-eth1-eth2.log

By default this will generate charts in PNG format in the current directory.

.. note::

  Your system may need to have `tk` installed and the instructions vary per OS and distribution.  On Ubuntu
  you can typically execute ``sudo apt-get install python-tk`` and it will install the system libraries you need.