Changes between Version 38 and Version 39 of GEMINIv1.1Tutorial


Ignore:
Timestamp:
10/23/12 15:32:58 (7 years ago)
Author:
carpenter@vis.uky.edu
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GEMINIv1.1Tutorial

    v38 v39  
    1 = The page is deprecated. Goto [wiki:GEMINI/Tutorial/GEC15] =
    2 
    3 [[PageOutline]]
    4 
    5 = Basic Experiment with GEMINI v1.1 I&M Tools: Instructions =
    6 
    7 
    8 
    9 == Preparation ==
    10 
    11 This tutorial assumes that attendees have a basic knowledge of ProtoGENI/InstaGENI, and we recommend that interested participants also consider attending the InstaGENI tutorial offered at GEC 15.  [[BR]]
    12 
    13 Active participants will need a laptop equipped with a recent version of [http://www.virtualbox.org/ Virtual Box]. If you are unable to bring one, you may partner with someone else.
    14 
    15 == Steps ==
    16 
    17 
    18 === 0)  Overview of experiment ===
    19 
    20 The instructions on this page are designed for the GEMINI Tutorial at GEC 15. This tutorial covers how to instrumentize a GENI slice using the GEMINI I&M system.
    21 
    22 The GEMINI I&M system provides an easy way to instrumentize a GENI slice with passive and active measurements. The current version of GEMINI provides host monitoring metrics (cpu, memory, network) and tools to perform on-demand and regular active measurements for throughput, one-way latency and round-trip latency (both with jitter and loss).
    23 
    24 Users can specify through their request RSpec which nodes should have passive instrumentation (e.g. host monitoring) and which nodes should active measurement services installed. While most passive instrumentation is always on, active measurements must be configured by the user. This is done through a web interface available on a instrumentized slice. A key service for this to work in GEMINI is UNIS: Unified Network Information Service.
    25 
    26 {{{
    27 UNIS and Topology-based Configuration: The Unified Network Information Service (UNIS) is the most important
    28 component of the GEMINI architecture. For those familiar with perfSONAR, this service is the combination of
    29 the Lookup Service and the Topology Service of the perfSONAR framework. UNIS stores the topology data of GENI
    30 slices, and services register themselves so that they can be found dynamically. The configuration of the
    31 active measurement services is done through annotations on the topology data. A web interface is provided to
    32 configure the active measurements and push the configuration to UNIS.
    33 }}}
    34 
    35 ==== 0.1)  Goals ====
    36 
    37 In this tutorial you will learn all the steps necessary to fully utilize the GEMINI I&M system, from instrumentizing and bootstrapping your slice to configuring measurements to visualizing and archiving the data.
    38 
    39 
    40 ==== 0.2)  Configuration ====
    41 
    42 For the tutorial given at GEC15, the slices will be pre-made and instrumentized.  The information for the slice will be given to you on an info sheet and you can also find your information [wiki:GEMINITutorial/SliceInformation here].  Make sure you are accessing your slice!
    43 
    44 
    45 ==== 0.3   Process  (flow chart) ====
    46 '''TODO'''
    47 
    48 
    49 === 1)  Establish experiment environment ===
    50 
    51 In order to make using GEMINI easier we provide a User Workspace Virtual Machine. The User Workspace is an environment that contains all of the tools and configuration necessary to set up your slice and install and configure the GEMINI instrumentation and measurement tools. These tools include:
    52 
    53 
    54   * GEMINI
    55     - /home/geniuser/Tutorials/GEMINI/common
    56        - The GEMINI tools and the rspec used in the tutorial (gec15.xml)
    57 
    58   * OMNI
    59     - Version 2.1 installed in /usr/local/bin/gcf
    60 
    61 
    62 More information about the User Workspace can be found at [http://groups.geni.net/geni/wiki/GENIUserWorkspace].
    63 
    64 Before configuring your slice, you will need to configure a few things for your user by following these [http://groups.geni.net/geni/wiki/GEC15TutorialVMInstructions instructions].
    65 
    66 After GEC15, you can configure your own GENI credentials according to the [http://groups.geni.net/geni/wiki/GENIUserWorkspace/ConfigCredentials Configuring Credentials] instructions.
    67 
    68 
    69 
    70 ==== 1.1)  Preparing the User workspace Virtual Machine ====
    71 
    72  * Install !VirtualBox
    73 
    74     Download the !VirtualBox software from http://www.virtualbox.org.
    75 
    76     If you already have !VirtualBox installed on your machine, make sure it is version 4.1 or above.
    77 
    78  *  Download !VirtualBox VM image for tutorials
    79 
    80     Download the !VirtualBox VM image (GEC15_Tutorials_Final.ova) from the website [https://www.planet-lab.org/GEC15/]
    81 
    82  *  Install the GEC15_Tutorials_Final.ova virtual machine image
    83 
    84     Start up !VirtualBox, select File->Import Appliance..., and follow the
    85     instructions.    Accept the default VM settings during the import.
    86 
    87     To run the virtual machine, go to the Oracle VM !VirtualBox Manager window, select the VM and click the
    88     green arrow labeled Start at the top of this window.
    89 
    90     If the install was successful, you should see the logon screen for
    91     the Ubuntu OS.
    92 
    93 
    94 ==== 1.2)  Gather necessary keys, certificates and credentials ====
    95 
    96 For the purpose of this tutorial we created temporal credentials. Follow these [http://groups.geni.net/geni/wiki/GEC15TutorialVMInstructions instructions].
    97 
    98 
    99 === 2)  Obtain slice of GENI resources, install I&M tools and experiment services ===
    100 {{{
    101 In order to save time, The steps in this section is already precooked for the purpose of this tutorial.
    102 }}}
    103 
    104 
    105 ==== 2.1)  Formulate slice topology for experiment, and build request rspec ====
    106 
    107 In order to use the GEMINI I&M system to instrument your slice, you have to add GEMINI specific rspec extensions to your slice. This can be done at the time you create your rspec. The GEMINI I&M system requires that you add an extra node with public IP address into your slice that we call as the GLOBAL Node (GN). This node does not need to have any links to any other nodes in your slice.
    108 
    109 To designate a node as a GLOBAL Node add the following section in the node section of the rspec as shown below
    110 {{{
    111 #!xml
    112 <gemini:node type="global_node">
    113   <gemini:monitor_urn name="urn:publicid:IDN+uky.emulab.net+authority+cm">
    114  </gemini:monitor_urn>
    115 </gemini:node>
    116 
    117 <!-- To make this node with public IP address -->
    118 <emulab:routable_control_ip xmlns="http://www.protogeni.net/resources/rspec/ext/emulab/1"/>
    119 
    120 }}}
    121 The monitor-urn tag defines which Aggregate's Node this Global Node is supposed to monitor. In our example above, this node is supposed to monitor the nodes at the Kentucky Aggregate.
    122 
    123 
    124 All other nodes (raw-pc or virtual nodes) to be monitored using GEMINI should be designated with a GEMINI rspec extension that defines them as a MP Node (measurement point node) as shown below
    125 {{{
    126 #!xml
    127 <gemini:node type="mp_node">
    128   <gemini:services>
    129     <gemini:active install="yes" enable="yes"/>
    130     <gemini:passive install="yes" enable="yes"/>
    131   </gemini:services>
    132 </gemini:node>
    133 
    134 }}}
    135 
    136 For each MP node you also have to define if you would like to have active or passive monitoring installed and/or enabled . The above snippet requests that both active and passive monitoring be installed and enabled on the node.
    137 
    138 Using the above mentioned GEMINI rspec extensions along with its xmlns schema definition in the rspec (xmlns:gemini="http://geni.net/resources/rspec/ext/gemini/1"), you can create a Slice which can later be instrumentized using GEMINI. For example, our Tutorial topology rspec would look like
    139 {{{
    140 #!xml
    141 <rspec type="request" generated_by="Flack" generated="2012-10-10T16:34:53Z" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd " xmlns:flack="http://www.protogeni.net/resources/rspec/ext/flack/1" xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gemini="http://geni.net/resources/rspec/ext/gemini/1" xmlns="http://www.geni.net/resources/rspec/3">
    142   <node client_id="VM-1" exclusive="false" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1">
    143     <rs:vnode name="pcvm62-6"/>
    144     <sliver_type name="emulab-openvz"/>
    145     <interface client_id="VM-1:if0">
    146       <ip address="10.128.2.2" netmask="" type="ipv4"/>
    147       <flack:interface_info addressUnset="false"/>
    148     </interface>
    149     <interface client_id="VM-1:if1">
    150       <ip address="10.128.3.2" netmask="" type="ipv4"/>
    151       <flack:interface_info addressUnset="false"/>
    152     </interface>
    153     <interface client_id="VM-1:if2">
    154       <ip address="10.128.4.1" netmask="" type="ipv4"/>
    155       <flack:interface_info addressUnset="false"/>
    156     </interface>
    157     <gemini:node type="mp_node">
    158       <gemini:services>
    159         <gemini:active install="yes" enable="yes"/>
    160         <gemini:passive install="yes" enable="yes"/>
    161       </gemini:services>
    162     </gemini:node>
    163     <services>
    164       <execute command="sudo /tmp/installer/installer.sh" shell="sh"/>
    165       <install install_path="/tmp" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/installer.tgz"/>
    166       <install install_path="/" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/sudoers.tgz"/>
    167     </services>
    168     <flack:node_info x="91" y="183" unbound="true"/>
    169   </node>
    170   <node client_id="VM-2" exclusive="false" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1">
    171     <rs:vnode name="pcvm62-7"/>
    172     <sliver_type name="emulab-openvz"/>
    173     <interface client_id="VM-2:if0">
    174       <ip address="10.128.1.1" netmask="" type="ipv4"/>
    175       <flack:interface_info addressUnset="false"/>
    176     </interface>
    177     <interface client_id="VM-2:if1">
    178       <ip address="10.128.4.2" netmask="" type="ipv4"/>
    179       <flack:interface_info addressUnset="false"/>
    180     </interface>
    181     <interface client_id="VM-2:if2">
    182       <ip address="10.128.6.2" netmask="" type="ipv4"/>
    183       <flack:interface_info addressUnset="false"/>
    184     </interface>
    185     <gemini:node type="mp_node">
    186       <gemini:services>
    187         <gemini:active install="yes" enable="yes"/>
    188         <gemini:passive install="yes" enable="yes"/>
    189       </gemini:services>
    190     </gemini:node>
    191     <services>
    192       <execute command="sudo /tmp/installer/installer.sh" shell="sh"/>
    193       <install install_path="/tmp" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/installer.tgz"/>
    194       <install install_path="/" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/sudoers.tgz"/>
    195     </services>
    196     <flack:node_info x="637" y="208" unbound="true"/>
    197   </node>
    198   <node client_id="VM-3" exclusive="false" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1">
    199     <rs:vnode name="pcvm62-8"/>
    200     <sliver_type name="emulab-openvz"/>
    201     <interface client_id="VM-3:if0">
    202       <ip address="10.128.3.1" netmask="" type="ipv4"/>
    203       <flack:interface_info addressUnset="false"/>
    204     </interface>
    205     <interface client_id="VM-3:if1">
    206       <ip address="10.128.5.1" netmask="" type="ipv4"/>
    207       <flack:interface_info addressUnset="false"/>
    208     </interface>
    209     <interface client_id="VM-3:if2">
    210       <ip address="10.128.6.1" netmask="" type="ipv4"/>
    211       <flack:interface_info addressUnset="false"/>
    212     </interface>
    213     <gemini:node type="mp_node">
    214       <gemini:services>
    215         <gemini:active install="yes" enable="yes"/>
    216         <gemini:passive install="yes" enable="yes"/>
    217       </gemini:services>
    218     </gemini:node>
    219     <services>
    220       <execute command="sudo /tmp/installer/installer.sh" shell="sh"/>
    221       <install install_path="/tmp" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/installer.tgz"/>
    222       <install install_path="/" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/sudoers.tgz"/>
    223     </services>
    224     <flack:node_info x="384" y="419" unbound="true"/>
    225   </node>
    226   <node client_id="VM-4" exclusive="false" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1">
    227     <rs:vnode name="pcvm62-9"/>
    228     <sliver_type name="emulab-openvz"/>
    229     <interface client_id="VM-4:if0">
    230       <ip address="10.128.1.2" netmask="" type="ipv4"/>
    231       <flack:interface_info addressUnset="false"/>
    232     </interface>
    233     <interface client_id="VM-4:if1">
    234       <ip address="10.128.2.1" netmask="" type="ipv4"/>
    235       <flack:interface_info addressUnset="false"/>
    236     </interface>
    237     <interface client_id="VM-4:if2">
    238       <ip address="10.128.5.2" netmask="" type="ipv4"/>
    239       <flack:interface_info addressUnset="false"/>
    240     </interface>
    241     <gemini:node type="mp_node">
    242       <gemini:services>
    243         <gemini:active install="yes" enable="yes"/>
    244         <gemini:passive install="yes" enable="yes"/>
    245       </gemini:services>
    246     </gemini:node>
    247     <services>
    248       <execute command="sudo /tmp/installer/installer.sh" shell="sh"/>
    249       <install install_path="/tmp" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/installer.tgz"/>
    250       <install install_path="/" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/sudoers.tgz"/>
    251     </services>
    252     <flack:node_info x="650" y="417" unbound="true"/>
    253   </node>
    254   <node client_id="GN" exclusive="false" xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1">
    255     <emulab:routable_control_ip xmlns="http://www.protogeni.net/resources/rspec/ext/emulab/1"/>
    256     <emulab:vnode name="pcvm62-10" xmlns="http://www.protogeni.net/resources/rspec/ext/emulab/1"/>
    257     <sliver_type name="emulab-openvz"/>
    258     <gemini:node type="global_node">
    259       <gemini:monitor_urn name="urn:publicid:IDN+uky.emulab.net+authority+cm">
    260     </gemini:monitor_urn></gemini:node>
    261     <services>
    262       <execute command="sudo /tmp/installer/installer.sh MC" shell="sh"/>
    263       <install install_path="/tmp" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/installer.tgz"/>
    264       <install install_path="/" url="http://www.uky.emulab.net/INSTOOLS/3.5/tarballs/sudoers.tgz"/>
    265     </services>
    266     <flack:node_info x="327" y="481" unbound="true"/>
    267   </node>
    268   <link client_id="lan0">
    269     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    270     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    271     <interface_ref client_id="VM-2:if0"/>
    272     <interface_ref client_id="VM-4:if0"/>
    273     <property source_id="VM-2:if0" dest_id="VM-4:if0"/>
    274     <property source_id="VM-4:if0" dest_id="VM-2:if0"/>
    275     <link_type name="lan"/>
    276     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    277   </link>
    278   <link client_id="lan1">
    279     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    280     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    281     <interface_ref client_id="VM-4:if1"/>
    282     <interface_ref client_id="VM-1:if0"/>
    283     <property source_id="VM-4:if1" dest_id="VM-1:if0"/>
    284     <property source_id="VM-1:if0" dest_id="VM-4:if1"/>
    285     <link_type name="lan"/>
    286     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    287   </link>
    288   <link client_id="lan2">
    289     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    290     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    291     <interface_ref client_id="VM-3:if0"/>
    292     <interface_ref client_id="VM-1:if1"/>
    293     <property source_id="VM-3:if0" dest_id="VM-1:if1"/>
    294     <property source_id="VM-1:if1" dest_id="VM-3:if0"/>
    295     <link_type name="lan"/>
    296     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    297   </link>
    298   <link client_id="lan3">
    299     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    300     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    301     <interface_ref client_id="VM-1:if2"/>
    302     <interface_ref client_id="VM-2:if1"/>
    303     <property source_id="VM-1:if2" dest_id="VM-2:if1"/>
    304     <property source_id="VM-2:if1" dest_id="VM-1:if2"/>
    305     <link_type name="lan"/>
    306     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    307   </link>
    308   <link client_id="lan4">
    309     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    310     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    311     <interface_ref client_id="VM-3:if1"/>
    312     <interface_ref client_id="VM-4:if2"/>
    313     <property source_id="VM-3:if1" dest_id="VM-4:if2"/>
    314     <property source_id="VM-4:if2" dest_id="VM-3:if1"/>
    315     <link_type name="lan"/>
    316     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    317   </link>
    318   <link client_id="lan5">
    319     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    320     <flack:link_info x="-1" y="-1" unboundVlantag="true" xmlns="http://www.protogeni.net/resources/rspec/ext/flack/1"/>
    321     <interface_ref client_id="VM-3:if2"/>
    322     <interface_ref client_id="VM-2:if2"/>
    323     <property source_id="VM-3:if2" dest_id="VM-2:if2"/>
    324     <property source_id="VM-2:if2" dest_id="VM-3:if2"/>
    325     <link_type name="lan"/>
    326     <flack:link_info x="-1" y="-1" unboundVlantag="true"/>
    327   </link>
    328 </rspec>
    329 
    330 }}}
    331 
    332 Visually this would look like
    333 
    334 [[Image(Topology.png,border=1)]]
    335 
    336 
    337 
    338 ==== 2.2)  Instrumentize process ====
    339 
    340 Things to verify before instrumenting your slice :
    341   1. Know the path to your GENI certificate file
    342   2. Know the passphrase for your GENI certificate file. GEMINI currently does not support decrypted/unencrypted GENI certificates. Its easier and less cumbersome if you can store your passphrase in ~/.ssl/password as explained in the User Workspace setup explained earlier.
    343   3. The sliver status for your slice is "READY".
    344   4. Make sure you can ssh into the nodes in your slice without being prompted for password. This functionality is one of the fundamental and necessary requirements of setting up the GEMINI I&M System on your slice.  See [http://groups.geni.net/geni/wiki/GEC15TutorialVMInstructions#SSLKeyPasswordConfiguration instructions] for adding your key to the ssh-agent.
    345   5. Renew your slice and slivers. Some certificates used in GEMINI are tied to your slice's expiration date and would need to be manually updated if your slice is renewed after the instrumentize process.
    346 
    347  
    348 In order to instrument your slice using GEMINI we use the script called "instrumentize.py" with the below mentioned parameters
    349   instrumentize.py -f <PATH TO YOUR GENI CREDENTIAL FILE> -n <SLICENAME>
    350  
    351 For example, in your User Workspace VM that your are using in this tutorial, do
    352 {{{
    353 #!sh
    354 geni@UserWorkspace:~$ cd ~/Tutorials/GEMINI/commmon/
    355 geni@UserWorkspace:~/Tutorials/GEMINI/commmon$./instrumentize.py -f /path/to/your/geni/credential/file -n some_slice_name
    356 }}}
    357 
    358 If you are experiencing problems , it is helpful to run the above command with a debug option enabled (- d) like below
    359 {{{
    360 #!sh
    361 geni@UserWorkspace:~/Tutorials/GEMINI/commmon$./instrumentize.py -d -f /path/to/your/geni/credential/file -n some_slice_name
    362 }}}
    363 
    364 While the instrumentize process is running you will see messages printed out on your terminal informing the action being performed at each stage of the process. In short, the list of steps being performed are
    365 
    366     1. Check all Nodes to be instrumentized for OS compatibility with the GEMINI Software
    367     2. Send your manifest to the UNIS Server (UNIS is mentioned in the GEMINI Documentation)
    368     3. Obtain Credential to view Active measurements
    369     4. Install all software required for the Passive measurements on the Global Node and Measurement points
    370     5. Install all software required for the Active measurements on the Global Node and Measurement points
    371     6. Send slice information to the GEMINI Portal
    372 
    373 Steps 4 and 5 do take considerable amount of time to complete, hence please be patient. ( currently around 20 minutes on VMs and 10 minutes when using raw nodes )
    374 
    375 
    376 On successful completion of the instrumentation process you will be given a username,password, link to the geminiportal website, and other information that you may need to login to the geminiportal site ([https://geminiportal.netlab.uky.edu/]). Please note this information down for use later. Below are screenshots of a GEMINI Instrumentation process and the execution flow of what you would see during this process.
    377 
    378 [[Image(instrumentize.png,border=1)]]
    379 
    380 
    381 
    382 [[Image(Instrumentize_running1.png,border=1)]]
    383 
    384 
    385 [[Image(instrumentize_running2.png,border=1)]]
    386 
    387 
    388 
    389 ==== 2.3)  Confirm slice with installed I&M tools and experiment services ====
    390 
    391 
    392 In order to access the GEMINI portal ([https://geminiportal.netlab.uky.edu/]) use the [wiki:GEMINITutorial/SliceInformation login information] that was given to you after the completion of the GEMINI Instrumentation process.
    393 Go to the GEMINI Portal website at [https://geminiportal.netlab.uky.edu/]
    394 
    395 [[Image(s6.png,border=1)]]
    396 
    397 
    398 
    399 
    400 === 3) Configure I&M tools and experiment services ===
    401 
    402 ==== 3.1)  Configuring Passive measurements ====
    403 
    404 [wiki:GeminiPortal Intro To Gemini Portal]
    405 
    406 
    407 ==== 3.2)   Configuring Active Measuremens ====
    408 
    409 
    410 The GEMINI I&M system in its current version facilitates regular measurements of throughput, one-way delay and round-trip delay. Other metrics like jitter and loss can also be derived from these measurements.
    411 
    412 The GEMINI services on a given node are configured by the pSConfig service. This service reads configuration stored in UNIS as part of the node's topology information and applies it to local configuration files. pSConfig will also start enabled services or stop disabled services that are running.
    413 
    414 We will now configure one-way (OWAMP) and round-trip (Ping) latency regular tests between VM1 and VM4.
    415 
    416 
    417 ===== 3.2.1 Accessing pSConfig UI =====
    418 
    419 To configure active measurements we access the pSConfig Web UI. You can find the URL by clicking on the MC node on the GEMINI portal, or by going to https://<gn node>/psconfig.
    420 
    421 [[Image(psconfig-portal.png)]]
    422 
    423 The certificate used by the web server is self-signed, so you will have to add an exception on the browser to proceed.
    424 
    425 [[Image(psconfig-secexception.png)]]
    426 
    427 After adding the exception you should see another pop-up for a certificate request. This time you're providing your user certificate to the service. Make sure the user that is shown for the certificate is the one assigned to you for the tutorial. In this example I'm using the user ''gemini20''. In case you did not see this pop-up or cannot see your user, please redo the steps on [wiki:GEMINIGEC15VMInstructions User Workspace - Accessing the portal].
    428 
    429 [[Image(psconfig-usercert.png)]]
    430 
    431 The main page of the pSConfig UI shows what services are currently enabled for each node. It also shows the last time we have synchronized with UNIS (remember that configuration information resides in UNIS). There are other agents that could be changing the information on UNIS, and the pSConfig UI will make sure we don't overwrite changes made since the last pull (i.e. a race condition). It is always a good idea to first pull the current configuration from UNIS before making changes.
    432 
    433 [[Image(0-unis.png)]]
    434 
    435 ===== 3.2.2 Enabling Services =====
    436 
    437 After we've made sure to have a recent copy of the topology information, we can move on to the Manage Services administration page. On this page we will enable the services required to perform on-demand and regularly scheduled tests. We start by enabling the  one-way latency services on VM1. Make sure to save the changes before continuing to the next node.
    438 
    439 [[Image(1-vm1-config.png)]]
    440 
    441 We then proceed to configure the services on node VM4. Since VM4 will receive OWMP probes, we will only enable the daemons for the tools used (owamp). Note that PingER is only enabled on VM4, and we will configure our Ping measurement on that node.
    442 
    443 
    444 [[Image(2-vm4-config.png)]]
    445 
    446 Now that we've enabled the services for our active measurements we will push the configuration to UNIS. To do this we need to go back to the Configuration Status page and then click the Push Configuration to UNIS. You can verify the list of services enabled for each node (i.e. the list in the image should match what you see).
    447 
    448 [[Image(2.0-unis-push.png)]]
    449 
    450 If everything goes well we should see a green message "Configuration pushed to UNIS.". However, the page auto reloads after this, so you might miss it if not paying attention. If there is no error message, the push completed successfully and the modification time will be 'never'.
    451 
    452 Success:
    453 
    454 [[Image(psconfig-managepushsuccess.png)]]
    455 
    456 Failure (unfortunately, you will have to redo the steps above in the case of a race condition):
    457 
    458 [[Image(psconfig-managepushfailure.png)]]
    459 
    460 
    461 ==== 3.3 Configuring Regular Active Measurements ====
    462 
    463 Enabling the OWAMP and BWCTL daemons is all we need to perform on-demand active measurements. However, it's usually better to have active measurements running regularly to analyze the performance over time. Throughput and ping tests can be scheduled with a given interval (e.g. every 30 minutes). One-way delay tests are scheduled as a stream (a constant amount of packets is sent per second).
    464 
    465 To schedule regular tests we go to the Schedule Tests administration page.
    466 
    467 [[Image(psconfig-schedule.png)]]
    468 
    469 We will schedule OWAMP tests from VM1 to VM4. We could schedule them on either endpoint, as long as both of them are running the appropriate pSBOUY Regular Testing service. In this case we schedule the tests on VM1 by selecting it and adding a new OWAMP test. Clicking the Add New One-Way Delay Test button will pop-up the options to configure the test. The description for the test is only important to you, the services don't use it directly. You can change the packet rate and the packet size used for the test, but we will use the default for the tutorial.
    470 
    471 [[Image(4-owamp-vm1-vm4-config.png)]]
    472 
    473 The test we've added establishes the test parameters for a given "star" mesh configuration. We can add multiple targets for this mesh (for OWAMP tests will run in parallel, for BWCTL measurements will be serialized). In this case we add VM4 as a target and save the test.
    474 
    475 [[Image(6-owamp-vm1-vm4-config.png)]]
    476 
    477 
    478 We also add a Ping test between nodes VM4 and VM1, scheduled at node VM4 (this is where we enabled the PingER service).
    479 
    480 [[Image(8-pinger-vm4-vm1-config.png)]]
    481 
    482 We can configure the standard ping parameters and the description for our test. The default has a relatively large packet size, so keep this in mind when analyzing the latency results (the ideal is to have packets the size of your experiment's packets). After creating the test we need to add our targets (VM1) and save the test. ''NOTE: You could use the 'Add New Host' button to add hosts outside of the slice (e.g. to ping geni.net).''
    483 
    484 [[Image(09-pinger-vm4-vm1-config.png)]]
    485 
    486 After adding all these tests we go back to the Configuration Status page and push the configuration to UNIS.
    487 
    488 [[Image(10-unis-push.png)]]
    489 
    490 ===== 3.3.1 Applying the Configuration =====
    491 
    492 pSConfig will pull the node's configuration from UNIS every 30 minutes (from the time it was started, not hh:00 and hh:30). Since we don't want to wait this long to start gathering data, we can restart pSConfig on each node by clicking the Apply Config link. This is achieved by ssh'ing to the node and restarting pSConfig, so errors are usually ssh related.
    493 
    494 [[Image(11-psconfig-apply.png)]]
    495 
    496 Make sure you apply the configuration on all three nodes. We will now run the user experiment to generate some heavier traffic on the slice before looking at the data.
    497 
    498  
    499  
    500 === 4)  Run and orchestrate I&M services and experiment services to complete run of experiment ===
    501 [[BR]]
    502 [wiki:PathControllerDemo Path Controller]
    503 
    504 
    505 === 5)  Analyze and visualize measurement results after completing run of experiment ===
    506 
    507  - if necessary, retrieve measurement results from archive service
    508  
    509  - analyze and format results as desired, for visualization with presentation service
    510  
    511  - as appropriate, store analyzed results and/or visualization in storage service
    512 
    513 
    514 ==== 5.1 . Visualize Measurement Data ====
    515 
    516 Doing the user experiment should have given the scheduled active measurements enough time to gather some data. We also generated some heavy traffic during our iperf data transfers. This section of the tutorial covers how to visualize the data for regular active tests. We will also check the passive monitoring graphs again to see how the iperf transfers affected our hosts.
    517 
    518 ===== 5.1.1 Accessing perfAdmin for Active Measurements Data =====
    519 
    520 To query and visualize the active measurements data we will use perfAdmin. perfAdmin is a web service that is able to query perfSONAR services and plot relevant data. You can access a perfAdmin instance running on your slice through the portal or by going to https://<gn node>/perfAdmin (note the capitalization).
    521 
    522 [[Image(perfadmin-portal.png)]]
    523 
    524 There are two sides to perfAdmin. The first side of perfAdmin is showing which services have registered to UNIS and are thus "known". The other side is querying a perfSONAR service (or set of services) for measurement data and displaying it to users.
    525 
    526 The landing page will show which services we know about from the information on UNIS. If this is your first time opening this page, you will probably be greeted with a blank page. The services should have had enough time to start and register themselves with UNIS. We pull the information from UNIS (make sure the last fetched date changes) and then refresh the page to make sure we have the latest information.
    527 
    528 [[Image(perfadmin-pull.png)]]
    529 
    530 After doing this we should see all the services we enabled during the configuration section for active services. ''NOTE: There are many reason why services might not show: pSConfig on the node hasn't pulled the configuration from UNIS yet (see Apply Config above); the services didn't have any data to register with UNIS (services usually register every 30 minutes or when changes are detected); or there might be a problem talking to UNIS. Please contact us if you're having trouble.''
    531 
    532 [[Image(perfadmin-services.png)]]
    533 
    534 On the list of services we can see the tool daemons for OWAMP and BWCTL. We can also see the perfSONAR services storing the Ping and OWAMP data from the tests we've configured. From this page we can query a given service to see the corresponding data. The active measurement data is stored on the node that initiates the measurements and is served by a perfSONAR service running on that node. For example, we can query the perfSONAR BUOY OWAMP MA on node VM1 to see the OWAMP data from VM1 to VM4.
    535 
    536 ''NOTE: When querying a single service, perfAdmin will first fetch all the metadata stored on that service. After obtaining the metadata, perfAdmin queries the service for data in order to build summaries and distinguish between active and inactive data sets. This process may take some time if there are many measurements stored on a given service.''
    537 
    538 [[Image(perfadmin-vm1.png)]]
    539 
    540 In this particular case we only have one OWAMP measurement stored at this service. We can graph by selecting a time range from the select box. perfAdmin will query the service for all data points within the last X hours and plot those (data points might be aggregated depending on granularity). The graphs are a little bit interactive, e.g. you can mouse over different data points and see the values for each direction.
    541 
    542 [[Image(perfadmin-owampgraph.png)]]
    543 
    544 The graph above shows two spikes measured latency and a lost packet during one of those. These spikes correspond to the iperf data transfers where we were saturating the links.
    545 
    546 We can access the Ping data from our scheduled test in a similar way. Going back to our Registered Services page, this time we access the PingER service on node VM4.
    547 
    548 
    549 While it's good to be able to query each service for its data, sometimes it's better to have access to all measurements in our slice on the same page. perfAdmin provides this option on the left menu for each of the regular testing measurement types currently supported (One-way Delay, Ping and Throughput). When we access one of these pages, perfAdmin will query each known service storing measurements of the given type for all the related metadata. It then builds a single page that we can use to query for a particular measurement's data. For example, if we go to the One-Way Delay page we should be able to see the measurements stored in both nodes VM1 and VM4.
    550 
    551 
    552 ===== 5.1.2 Changes in Passive Monitoring Graphs =====
    553 
    554 Using the GEMINI Portal, you can also view the changes in Passively monitored Network traffic and system resources when running any experiment or traffic or any other kind of load on the nodes in your slice.
    555 [[BR]]
    556 [[BR]]
    557 
    558  
    559 
    560 === 6)  Move selected collected measurements and other artifacts from storage service to long-term archive service ===
    561 
    562  - identify archived objects with persistent identifier
    563  
    564  - include policy for sharing with others
    565  
    566  - allow retrieval for further analysis and visualization
    567 
    568 
    569 === 7)  Release experiment resources  ===
     1= The page is deprecated. =
     2== Goto [wiki:GEMINI/Tutorial/GEC15] ==