wiki:OTM-Gush

Version 2 (modified by Prasad Calyam, 8 years ago) (diff)

--

User Manual for OnTime Control using Gush

Prasad Calyam, Alex Berryman, Kunpeng Zhu
Mar 08, 2011

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.

Gush is an experiment workflow tool that runs on a user desktop and executes commands on Client nodes in a GENI Slice.

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 Experimenter Tutorial.

For details regarding OnTimeMeasure, please visit OnTimeMeasure Wiki.

For details regarding OnTime Control, please visit OnTime Control Wiki.
(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 Gush Wiki.

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

  1. ProtoGENI/PlanetLab slice with OnTimeMeasure software installed and running.
  1. 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.
  1. 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>
  1. 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.
  1. 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

Attachments (10)

Download all attachments as: .zip