= GENI Experimenters How-to Using Omni tools =

This page provides an overview of the actions required by an experimenter to run a GENI experiment using resources from multiple resource aggregates.  While working through these examples, you may need to interact with the GENI Infrastructure group to setup specific resources for you (e.g. VLAN or OF VLAN), at a high level, the steps to run a GENI Experiment include:

  * Get credentials from '''one''' Clearinghouse, this allows you to access multiple aggregates.[[BR]]
  * Install and configure Omni tools [[BR]]
  * Use the Omni tools to create a slice [[BR]]
  * Request resources from one or more aggregates to add to the slice [[BR]]
  * and of course, run the experiment.


[[Image(GENIExperimenter-workflow.jpg)]]

This page focuses on resource allocation with Omni tools, other tools exists to assist the experimenter with resource allocation but are not covered here. 

=== Examples ===
Two supporting examples are provided to illustrate the steps needed to run an experiment with GENI resources, each example has a unique scope:

  * [wiki:GENIExperimenter/ExperimentExample GENI Experiment Example 1] covers how to configure and use Omni tools to reserve compute resources from multiple resource aggregates (PG & PL). This example has no specific network requirement, it simply focuses on getting host resources allocated for an experiment.

 * [wiki:GENIExperimenter/ExperimentExample-OF GENI OpenFlow Experiment Example 2] covers how to use Omni tools to request !OpenFlow resources as part of an experiment that also uses PG & MyPLC compute resources. The scenario assumes that the experimenter is running an OF controller.


== 1. Get GENI Credentials ==

To access GENI resources, an experimenter must have GENI credentials! If you don't have credentials, follow the instructions at SignMeUp.

'''Note:''' If you have an account with a Clearinghouse other than pgeni.gpolab.bbn.com (e.g. www.emulab.net, planet-lab.org) you can still use Omni to reserve resources but you will not be able to complete the above two examples so we strongly recommend that you [wiki:SignMeUp sign up] with GPO's clearing house. 

== 2. Get Omni Tools ==

To get access to the GENI resources you can use the OMNI client which is part of the [http://trac.gpolab.bbn.com/gcf/wiki GENI Control Framework] (GCF) software package.  Get the GCF package at this [http://trac.gpolab.bbn.com/gcf/wiki/GettingGcf GCF location] and install it using the [http://trac.gpolab.bbn.com/gcf/wiki/OmniQuickStart Quick Start] instructions. 

Once the [http://trac.gpolab.bbn.com/gcf/wiki/Omni Omni tool] is installed, follow the [http://trac.gpolab.bbn.com/gcf/wiki/OmniConfigure configuration instructions]. 

== 3. Define Required Resources ==

You are now ready to define the resources required for your experiment. For an overview of available GENI resource see the [wiki:AvailableAggregates Available Aggregates] page. the The Omni tools can be used to query a Aggregate Managers that support the [wiki:GeniApi GENI AM API] to get a list of available resources. In GENI we use [wiki:GENIExperimenter/RSpecs Resource Specification (RSpec) documents] to describe resources. In the supporting  [#Examples examples] it is explained how to create and use rspecs. 

If while you are gathering your resources you believe you need a layer 2 connection between different sites, then please contact us at [mailto:help@geni.net]. You can also skim through the [wiki:ConnectivityOverview connectivity overview page] that provides a summary of connectivity options between sites, or take a look at [#Layer2ConnectivityInformation this Section], but if you do not know where to start please [mailto:help@geni.net email us]. 

== 4. Get Resources ==
The Omni tool can help you reserve resources.  In the supporting [wiki:GENIExperimenter/ExperimentExample GENI Experiment Example 1] page, examples are provides that show how to:
  * [wiki:GENIExperimenter/ExperimentExample#Listavailableresources List available resources] in the PG and PL aggregates.
  * [wiki:GENIExperimenter/ExperimentExample#Createaslice Create a Slice] in the Clearinghouse
  * [wiki:GENIExperimenter/ExperimentExample#AddEmulabPGresourcestoGPOPGslice Add Emulab PG nodes] to GPO PG slice.
  * [wiki:GENIExperimenter/ExperimentExample#AddPlanetLabresourcestoGPOPGslice Add PL nodes] to GPO PG slice.
  * [wiki:GENIExperimenter/ExperimentExample#Checkingsliverresourcestatus Check Resource Status].

Similarly, for an experiment using OpenFlow resources, see the [wiki:GENIExperimenter/ExperimentExample-OF GENI OpenFlow Experiment Example 2] page, which also provides examples as in the above.  For additional details on how to get framework resources: within !PlanetLab see the  [http://trac.gpolab.bbn.com/gcf/wiki/OmniPlanetLab Omni PlaneLab] page, or within ProtoGENI Emulab see the [http://trac.gpolab.bbn.com/gcf/wiki/OmniProtoGeni Omni ProtoGENI] page. 

== 5. Run Experiment ==

Once your resources are ready, you may now run your experiment.

Remember to monitor the expiration time for your slice for each of the resource aggregates with the Omni ''sliverstatus'' option and to extend expiration as needed with the ''renewsliver'' option.  An example for checking the ''sliverstatus'' and ''renewsliver'' can be found [wiki:GENIExperimenter/ExperimentExample#Checkingsliverresourcestatus here].

When your experiment is completed, you should [wiki:GENIExperimenter/ExperimentExample#Deletesliverresources delete slivers] to release your resources from each resource aggregate used.

=== Layer 2 Connectivity Information ===
The following VLAN options are available for GENI Experiments:

  1. ProtoGENI VLAN (Internet2 only) available via the ProtoGENI [http://protogeni.net/flack.html Flack] client.
  2. !OpenFlow VLAN, current state available at GENI [wiki:NetworkCore Network Core] page
  3. Static VLANs which are setup for NLR, Internet2, Regional Providers, and Campuses.

If you are planning to use static or OF VLANs in your GENI experiment, you can reference the GENI [wiki:ConnectivityHome Connectivity Home] page for background and recommendations to set up GENI connections and experiments. Static VLAN are mostly set up as single or multiple VLANs that may or may not use VLAN Translation.  There are other options, which are less common and they include: Layer 2 Tunneling, Direct Fiber Connection, and Higher Layer Tunneling.  A high level overview of these VLAN connectivity options is available at the [wiki:ConnectivityOverview Connectivity Overview] page.  Detailed steps required to acquire various types of connections between two campuses are captured at [wiki:ConnectivityGuidelines VLAN Connectivity Guidelines] page.  Also for a list of supported !OpenFlow VLAN options for your campus you may refer to the [wiki:ConnectivityOptions Connectivity Options] page.    

To implement your VLAN choice you can contact [mailto:help@geni.net help@geni.net], with a request that defines your VLAN requirements. In the request you should capture the following details:
  * VLAN connection type [[BR]]
  * your campus VLAN details [[BR]]
  * the regional networks provider for the sites/campuses you plan to use [[BR]]
  * the national research backbone(s) for your sites.  [[BR]]
If you are not sure what Site/Regional/Backbone VLAN resources you are using, you can get assistance at [mailto:help@geni.net help@geni.net].

If you are planning to use !OpenFlow (OF) VLAN resources for your experiment you can use Omni tools to query and request OF resources from a site !OpenFlow Aggregate Manager. The [wiki:GENIExperimenter/ExperimentExample-OF GENI OpenFlow Experiment Example 2] page captures an OF Experiment and walks through the Authentication, Omni tools configuration, Resource Allocation, Opt-in Manager Administrative approval, up to running an experiment.

If you require help to set up your OF resources, support is available at [mailto:help@geni.net help@geni.net], where you will get support to get the OF VLAN resources needed for your experiment and provide the following details: resource needed, location of the resource, and experiment characteristics (Speed, Bandwidth requirements, etc).  Details required for the OF VLAN depend on the experiment, therefore the list of information required will vary for your experiment.  For additional information on how to configure Omni tools see the [http://trac.gpolab.bbn.com/gcf/wiki/OmniOpenFlow Omni OpenFlow] page for details.

----
{{{
#!html
Email <a href="mailto:help@geni.net"> help@geni.net </a> for GENI support or email <a href="mailto:luisa.nevers@bbn.com">me</a> with feedback on this page!
}}}