User Manual for OnTime Control using Gush

Prasad Calyam, Alex Berryman, Kunpeng Zhu, Yingxiao Xu
February 10, 2012

Software License: 'GENI Project License (GPL)'

Overview

This document describes the installation, configuration and usage of ​OnTime Control with the ​Gush tool.

OnTime Control is a command-line interface client for OnTimeMeasure users to login, manage slice information and control Node/Root Beacons within their slices in an automated manner.
For details regarding OnTime Control, please visit ​OnTime Control Wiki.
(Note: This wiki explains how to install OnTime Control with Gush, and how to use the Gush interface to interact with the measurement service. This method can be used instead of installing the OnTime Control package directly on your user desktop as described in ​http://groups.geni.net/geni/wiki/OTM-Control. )

Gush is an experiment workflow tool that runs on a user desktop and executes commands on Client nodes in a GENI Slice.
For details regarding Gush, please visit ​Gush Wiki.

OnTimeMeasure is a measurement service for the GENI facility users. The measurement service can be used to perform centralized and distributed orchestration and provisioning of measurements within experiment slices for purposes such as:

• Network paths monitoring
• Network weather forecasting
• Network performance anomaly detection
• Network-bottleneck fault-location diagnosis

For details regarding OnTimeMeasure, please visit ​OnTimeMeasure Wiki.

Before proceeding further, we highly recommend reading the ​Experimenter Tutorial.

OnTimeMeasure User Workflow Steps

1. Install OnTimeMeasure software / OnTime Contol for Gush (Contents of this wiki)
2. Configure / Resource Setup
3. Submit Measurement Request
4. Manage Measurement Service
5. Query data/graphs/archive/dashboard

Features implemented in OnTime Control with Gush include

• Manage requests for centralized measurement
• Start/Stop measurement service
• Check measurement service status
• Query measurement results
• Query measurement archive
• Run a distributed measurement request

Topology Overview

• Your Existing RootBeacon and NodeBeacon reside in your slice.
• You install the OnTimeControl-Gush onto your Gush controller/User Desktop.
• Using the OnTimeControl-deploy.xml within Gush OnTimeControl is deployed onto your RootBeacon.

1. Installation of OnTimeControl on Root Beacon

Requirements

1. ProtoGENI/PlanetLab slice with OnTimeMeasure software installed and running.

For ProtoGENI slice creation, see - ​OnTimeMeasure-ProtoGENI For PlanetLab slice creation, see - ​OnTimeMeasure-PlanetLab

2. Gush installed and configured as described on the ​Gush Wiki

Instructions

1. Download and extract the ​OnTimeControl-Gush.tar.gz tarball to your Gush directory.

2. Customize your Gush directory.xml file to include an ssh resource with the group="OTMGUSH_Control" defined (Note: The hostname and user should correspond to the details for your Root Beacon):

<?xml version="1.0" encoding="UTF-8"?>
<gush>
    <resource_manager type="planetlab">
        <user>berryman@oar.net</user>
        <allsites>allsites.xml</allsites>
        <port_map slice="ohiostate_OTMGUSH" port="15414"/>
    </resource_manager>
    <resource_manager type="ssh">
    <node hostname ="pl2.ucs.indiana.edu:15888" user="ohiostate_OTMGUSH" group="OTMGUSH_Control" identity="~/.ssh/id_rsa.pub"/>
    </resource_manager>
</gush>

3. Launch Gush and connect to your Root Beacon. Load and Run the OnTimeControl-deploy.xml​

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-deploy.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-Deploy" is selected.

gush> run
Starting experiment run.
Running experiment OnTimeControl-Deploy...
gush> The configuration matcher has finished matching.
The resource allocator has finished successfully.
The file transfer of Package to earth.cs.brown.edu has been completed.
The software installation of Package on earth.cs.brown.edu was successful.
ohiostate_OTCGUSH@earth.cs.brown.edu:15888,17929: config_example.yaml
direct_client.py
loader.py
measurement.yaml
portal_client.py
query.py
request_measurement_archive.py
service_control.py
service_status.py
session_support.py
task_manage.py
yaml

The experiment has ended.

2. Configuration

1. Manully edit the config.yaml, and the measurement.yaml file included in the tarball.
   Note: Follow instructions within the file to configure the OnTime Control software. It is strongly suggested to use the "direct" connection mode. The "portal" mode is a legacy capability.

2. Upload the edited config.yaml, and the measurement.yaml files to the <rootbeacon hostname>:~/OnTimeControl/

3. Submit Requests

OnTimeControl-task_manage.xml​ manages the measurement tasks, which are configured in a YAML file. An example "measurement.yaml" is included in the package with contents:

# Measurement task settings
# Hint: A space is required after ':'

##################################################
# Supported patters:
# - Periodic
# - RandomPoisson
# - RandomExponential
# - RandomGaussian
# - StratifiedRandom
# - Adaptive
##################################################
pattern: Periodic

##################################################
# Measurement links
# Please use node names as source and destination
# Supported metrics:
# - RoundtripDelay
# - Throughput
# - Loss
# - Jitter
# - RouteChanges
##################################################
links:
- source: WASH
  destination: SALT
  metric: [Throughput, RoundtripDelay, Jitter, RouteChanges]

- source: SALT
  destination: WASH
  metric: [Jitter, RoundtripDelay, Throughput, RouteChanges]

Edit the measurement.yaml configuration file by following the example and comments in the file. Then run the OnTimeControl-task_manage.xml​ from Gush.

An example:

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-task_manage.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-task_manage" is selected.

gush> run

4. Manage Service

4.1 Check measurement service status

Launch Gush and connect to your Root Beacon. Load and Run the OnTimeControl-status.xml​

[berryman@gushcontroller gush]$ ./gush -P 15888 #Start Gush on TCP Port 1588
gush> connect pl2.ucs.indiana.edu:15888 #Connect to root beacon
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-status.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-status" is selected.

gush> run

4.2 Measurement service control

To control the measurement service, load and run the corresponding file OnTimeControl-start.xml​, OnTimeControl-stop.xml​, OnTimeControl-restart.xml​.

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-restart.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-restart" is selected.

gush> run

5. Query the Results

5.1 Query measurement results for a specific period or metric

OnTimeControl-query.xml​ queries the measurement results. Parameters for the query are:

-f from time "YYYY-MM-DD HH:MM:SS" in UTC
-t to time "YYYY-MM-DD HH:MM:SS" in UTC
-s source node name
-d destination node name
-m metric {RountTripDelay|Throughput|Loss|Jitter}
-r result type {RawFiles|TimeSeries|TimeSeriesPlusAnomalies|TimeSeriesPlusForecasts}

The parameters are specified within the OnTimeControl-query.xml​ file:

<?xml version="1.0" encoding="utf-8"?>
<gush>
  <project name="OnTimeControl">
    <component name="RootBeacon">
      <rspec>
        <num_hosts>1</num_hosts>                                           //Number of remote clients
      </rspec>
      <resources>
        <resource type="ssh" group="OTMGUSH_Control"/>
      </resources>
    </component>
    <experiment name="OnTimeControl-query">
      <execution>
        <component_block name="cb1">
  	  <component name="RootBeacon" />
	  <process_block name="p2">  
  	    <process name="python">                                     
	      <path>python</path>                                          
	      <cmdline>                  
 	        <arg>OnTimeControl/query.py -f "2010-09-15 11:00:00" -t "2010-09-30 12:00:00" -s node1 -d node2 -m RoundTripDelay -r TimeSeries</arg>
	      </cmdline>
	      <cwd/>
	    </process>
	  </process_block>
	</component_block>
      </execution>
    </experiment>
  </project>
</gush>

An example query:

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-query.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-query" is selected.

gush> run

5.2 Query the entire measurement archive

OnTimeControl-request_archive.xml​ queries the measurement archive in the Root Beacon and displays the URL to download the archive file.

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-request_archive.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-request_archive" is selected.

gush> run

6. Integrate Custom Metric of Experiment with OnTimeMeasure

OnTimeControl-add_metric.xml​ integrate custom metric of experiment with OnTimeMeasure.

You should prepare a metric specification file (Specs.yaml) and a parser file (Parser.pm).

A sample can be downloaded from ​http://ontime.oar.net/INSTALL/metric/CPU.tgz

[berryman@gushcontroller gush]$ ./gush -P 15888
gush> connect pl2.ucs.indiana.edu:15888
Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.

gush> load OnTimeControl-add_metric.xml
Project "OnTimeControl" is selected.
Experiment "OnTimeControl-add-metric" is selected.

gush> run