Changes between Initial Version and Version 1 of OTM-Gush


Ignore:
Timestamp:
03/08/11 21:36:57 (11 years ago)
Author:
Prasad Calyam
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OTM-Gush

    v1 v1  
     1= User Manual for !OnTime Control using Gush =
     2'''Prasad Calyam, Alex Berryman, Kunpeng Zhu'''[[BR]]
     3'''Mar 08, 2011'''
     4
     5''Software License:'' [http://www.geni.net/wp-content/uploads/2009/02/geniprojlic.pdf ''GENI Project License (GPL)'']
     6
     7== Overview ==
     8This document describes the installation, configuration and usage of !OnTime Control with the Gush tool.
     9
     10!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''.
     11
     12Gush is an experiment workflow tool that runs on a user desktop and executes commands on Client nodes in a GENI Slice. [[BR]]
     13
     14!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:
     15
     16 * Network paths monitoring
     17 * Network weather forecasting
     18 * Network performance anomaly detection
     19 * Network-bottleneck fault-location diagnosis
     20
     21Before proceeding further, we highly recommend reading the [http://groups.geni.net/geni/attachment/wiki/OnTimeMeasure/OnTimeMeasure_Tutorial.pdf Experimenter Tutorial].
     22
     23For details regarding !OnTimeMeasure, please visit [http://groups.geni.net/geni/wiki/OnTimeMeasure OnTimeMeasure Wiki].[[BR]]
     24
     25For 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)
     26
     27For details regarding Gush, please visit [http://gush.cs.williams.edu Gush Wiki].[[BR]]
     28
     29!OnTimeMeasure User Workflow Steps:
     30
     31   1. Install !OnTimeMeasure software / !OnTime Contol for Gush ''(Contents of this wiki)''
     32   2. Configure / Resource Setup
     33   3. Submit Measurement Request
     34   4. Manage Measurement Service
     35   5. Query data/graphs/archive/dashboard
     36
     37Features implemented in !OnTime Control with Gush include:
     38 * Manage requests for centralized measurement
     39 * Start/Stop measurement service
     40 * Check measurement service status
     41 * Query measurement results
     42 * Query measurement archive
     43 * Run a distributed measurement request
     44
     45== 1. Installation of !OnTimeControl on Root Beacon ==
     46
     47=== Requirements ===
     48
     49A. ProtoGENI/PlanetLab slice with !OnTimeMeasure software installed and running.
     50
     51B. Gush installed and configured as described on the [http://gush.cs.williams.edu/trac/gush "Gush Wiki"]
     52
     53=== Instructions ===
     54
     55 1. Download and extract the [http://ontime.oar.net/download/OnTimeControl-Gush.tar.gz OnTimeControl-Gush.tar.gz] tarball to your Gush directory.
     56
     57 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):
     58 
     59{{{
     60#!xml
     61<?xml version="1.0" encoding="UTF-8"?>
     62<gush>
     63    <resource_manager type="planetlab">
     64        <user>berryman@oar.net</user>
     65        <allsites>allsites.xml</allsites>
     66        <port_map slice="ohiostate_OTMGUSH" port="15414"/>
     67    </resource_manager>
     68    <resource_manager type="ssh">
     69    <node hostname ="pl2.ucs.indiana.edu:15888" user="ohiostate_OTMGUSH" group="OTMGUSH_Control" identity="~/.ssh/id_rsa.pub"/>
     70    </resource_manager>
     71</gush>
     72}}}
     73
     74 3. Launch Gush and connect to your Root Beacon. Load and Run the [attachment:OnTimeControl-deploy.xml OnTimeControl-deploy.xml]
     75
     76{{{
     77#!sh
     78[berryman@gushcontroller gush]$ ./gush -P 15888
     79gush> connect pl2.ucs.indiana.edu:15888
     80Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     81ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     82
     83gush> load OnTimeControl-deploy.xml
     84Project "OnTimeControl" is selected.
     85Experiment "OnTimeControl-Deploy" is selected.
     86
     87gush> run
     88Starting experiment run.
     89Running experiment OnTimeControl-Deploy...
     90gush> The configuration matcher has finished matching.
     91The resource allocator has finished successfully.
     92The file transfer of Package to earth.cs.brown.edu has been completed.
     93The software installation of Package on earth.cs.brown.edu was successful.
     94ohiostate_OTCGUSH@earth.cs.brown.edu:15888,17929: config_example.yaml
     95direct_client.py
     96loader.py
     97measurement.yaml
     98portal_client.py
     99query.py
     100request_measurement_archive.py
     101service_control.py
     102service_status.py
     103session_support.py
     104task_manage.py
     105yaml
     106
     107The experiment has ended.
     108}}}
     109
     110
     111== 2. Configuration ==
     112
     113 1. Manully edit the config.yaml, and the measurement.yaml file included in the tarball. [[br]]
     114  '''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.
     115
     116 2. Upload the edited  config.yaml, and the measurement.yaml files to the <rootbeacon hostname>:~/!OnTimeControl/
     117
     118== 3. Submit Requests ==
     119
     120[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:
     121
     122{{{
     123# Measurement task settings
     124# Hint: A space is required after ':'
     125
     126##################################################
     127# Supported patters:
     128# - Periodic
     129# - RandomPoisson
     130# - RandomExponential
     131# - RandomGaussian
     132# - StratifiedRandom
     133# - Adaptive
     134##################################################
     135pattern: Periodic
     136
     137##################################################
     138# Measurement links
     139# Please use node names as source and destination
     140# Supported metrics:
     141# - RoundtripDelay
     142# - Throughput
     143# - Loss
     144# - Jitter
     145# - RouteChanges
     146##################################################
     147links:
     148- source: WASH
     149  destination: SALT
     150  metric: [Throughput, RoundtripDelay, Jitter, RouteChanges]
     151
     152- source: SALT
     153  destination: WASH
     154  metric: [Jitter, RoundtripDelay, Throughput, RouteChanges]
     155}}}
     156
     157Edit 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.
     158
     159An example:
     160
     161{{{
     162#!sh
     163[berryman@gushcontroller gush]$ ./gush -P 15888
     164gush> connect pl2.ucs.indiana.edu:15888
     165Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     166ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     167
     168gush> load OnTimeControl-task_manage.xml
     169Project "OnTimeControl" is selected.
     170Experiment "OnTimeControl-task_manage" is selected.
     171
     172gush> run
     173}}}
     174
     175== 4. Manage Service ==
     176
     177=== 4.1 Check measurement service status ===
     178
     179Launch Gush and connect to your Root Beacon. Load and Run the [attachment:OnTimeControl-status.xml OnTimeControl-status.xml]
     180
     181{{{
     182#!sh
     183[berryman@gushcontroller gush]$ ./gush -P 15888 #Start Gush on TCP Port 1588
     184gush> connect pl2.ucs.indiana.edu:15888 #Connect to root beacon
     185Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     186ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     187
     188gush> load OnTimeControl-status.xml
     189Project "OnTimeControl" is selected.
     190Experiment "OnTimeControl-status" is selected.
     191
     192gush> run
     193
     194}}}
     195
     196
     197
     198=== 4.2  Measurement service control ===
     199
     200To 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].
     201
     202{{{
     203#!sh
     204[berryman@gushcontroller gush]$ ./gush -P 15888
     205gush> connect pl2.ucs.indiana.edu:15888
     206Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     207ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     208
     209gush> load OnTimeControl-restart.xml
     210Project "OnTimeControl" is selected.
     211Experiment "OnTimeControl-restart" is selected.
     212
     213gush> run
     214}}}
     215
     216== 5. Query the Results ==
     217
     218=== 5.1 Query measurement results for a specific period or metric ===
     219
     220[attachment:OnTimeControl-query.xml OnTimeControl-query.xml] queries the measurement results. Parameters for the query are:
     221
     222  {{{
     223-f from time "YYYY-MM-DD HH:MM:SS" in UTC
     224-t to time "YYYY-MM-DD HH:MM:SS" in UTC
     225-s source node name
     226-d destination node name
     227-m metric {RountTripDelay|Throughput|Loss|Jitter}
     228-r result type {RawFiles|TimeSeries|TimeSeriesPlusAnomalies|TimeSeriesPlusForecasts}
     229}}}
     230
     231The parameters are specified within the [attachment:OnTimeControl-query.xml OnTimeControl-query.xml] file:
     232{{{
     233<?xml version="1.0" encoding="utf-8"?>
     234<gush>
     235  <project name="OnTimeControl">
     236    <component name="RootBeacon">
     237      <rspec>
     238        <num_hosts>1</num_hosts>                                           //Number of remote clients
     239      </rspec>
     240      <resources>
     241        <resource type="ssh" group="OTMGUSH_Control"/>
     242      </resources>
     243    </component>
     244    <experiment name="OnTimeControl-query">
     245      <execution>
     246        <component_block name="cb1">
     247          <component name="RootBeacon" />
     248          <process_block name="p2"> 
     249            <process name="python">                                     
     250              <path>python</path>                                         
     251              <cmdline>                 
     252                <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>
     253              </cmdline>
     254              <cwd/>
     255            </process>
     256          </process_block>
     257        </component_block>
     258      </execution>
     259    </experiment>
     260  </project>
     261</gush>
     262
     263}}}
     264
     265An example query:
     266{{{
     267#!sh
     268[berryman@gushcontroller gush]$ ./gush -P 15888
     269gush> connect pl2.ucs.indiana.edu:15888
     270Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     271ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     272
     273gush> load OnTimeControl-query.xml
     274Project "OnTimeControl" is selected.
     275Experiment "OnTimeControl-query" is selected.
     276
     277gush> run
     278}}}
     279
     280=== 5.2 Query the entire measurement archive ===
     281
     282[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.
     283
     284{{{
     285#!sh
     286[berryman@gushcontroller gush]$ ./gush -P 15888
     287gush> connect pl2.ucs.indiana.edu:15888
     288Connecting to host ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888.
     289ohiostate_OTMGUSH@pl2.ucs.indiana.edu:15888 has joined the mesh.
     290
     291gush> load OnTimeControl-request_archive.xml
     292Project "OnTimeControl" is selected.
     293Experiment "OnTimeControl-request_archive" is selected.
     294
     295gush> run
     296}}}