= 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 }}}