Changes between Initial Version and Version 1 of OTM-Gush

Timestamp:

03/08/11 21:36:57 (13 years ago)

Author:

Prasad Calyam

Comment:

--

OTM-Gush

@@ +1 @@
+= 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
+<?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 [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 <rootbeacon hostname>:~/!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:
+{{{
+<?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:
+{{{
+#!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
+}}}