= User Manual for !OnTime Control using Gush =
'''Prasad Calyam, Alex Berryman, Kunpeng Zhu'''[[BR]]
'''Mar 08, 2011'''
''Software License:'' [http://www.geni.net/wp-content/uploads/2009/02/geniprojlic.pdf ''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''.
Gush is an experiment workflow tool that runs on a user desktop and executes commands on Client nodes in a GENI Slice. [[BR]]
!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
Before proceeding further, we highly recommend reading the [http://groups.geni.net/geni/attachment/wiki/OnTimeMeasure/OnTimeMeasure_Tutorial.pdf Experimenter Tutorial].
For details regarding !OnTimeMeasure, please visit [http://groups.geni.net/geni/wiki/OnTimeMeasure OnTimeMeasure Wiki].[[BR]]
For details regarding !OnTime Control, please visit [http://groups.geni.net/geni/wiki/OTM-Control OnTime Control Wiki].[[BR]] ('''Note:''' This wiki explains how to install !OnTime Control with Gush, and so you do not need to follow the install instructions in the !OnTime Control Wiki)
For details regarding Gush, please visit [http://gush.cs.williams.edu Gush Wiki].[[BR]]
!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
== 1. Installation of !OnTimeControl on Root Beacon ==
=== Requirements ===
A. ProtoGENI/PlanetLab slice with !OnTimeMeasure software installed and running.
B. Gush installed and configured as described on the [http://gush.cs.williams.edu/trac/gush "Gush Wiki"]
=== Instructions ===
1. Download and extract the [http://ontime.oar.net/download/OnTimeControl-Gush.tar.gz 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
berryman@oar.net
allsites.xml
}}}
3. Launch Gush and connect to your Root Beacon. Load and Run the [attachment:OnTimeControl-deploy.xml OnTimeControl-deploy.xml]
{{{
#!sh
[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. [[br]]
'''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 :~/!OnTimeControl/
== 3. Submit Requests ==
[attachment:OnTimeControl-task_manage.xml 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 [attachment:OnTimeControl-task_manage.xml OnTimeControl-task_manage.xml] from Gush.
An example:
{{{
#!sh
[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 [attachment:OnTimeControl-status.xml OnTimeControl-status.xml]
{{{
#!sh
[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 [attachment:OnTimeControl-start.xml OnTimeControl-start.xml], [attachment:OnTimeControl-stop.xml OnTimeControl-stop.xml], [attachment:OnTimeControl-restart.xml OnTimeControl-restart.xml].
{{{
#!sh
[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 ===
[attachment:OnTimeControl-query.xml 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 [attachment:OnTimeControl-query.xml OnTimeControl-query.xml] file:
{{{
1 //Number of remote clients
python
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
}}}
An example query:
{{{
#!sh
[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 ===
[attachment:OnTimeControl-request_archive.xml OnTimeControl-request_archive.xml] queries the measurement archive in the Root Beacon and displays the URL to download the archive file.
{{{
#!sh
[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
}}}