[[PageOutline(3, Table of Contents)]]

= Using GENI-in-a-Box =

This page describes how to install and use [wiki:GENI-in-a-Box] on your computer. 


=== Install GENI-in-a-Box ===
''Please make sure you have [https://www.virtualbox.org VirtualBox] Version 4.1.16 or later installed on your computer.''

1. Start up !VirtualBox and from the !VirtualBox "File" menu, select "Import Appliance...".

2. The !VirtualBox Appliance Wizard will start up and guide you through the import of the GENI-in-a-Box virtual machine image you downloaded.  Please accept the default VM settings during the import.

3. When the import is done, and entry for GENI-in-a-Box will appear in the Oracle VM !VirtualBox Manager window.  Select this entry and click the green arrow labeled Start at the top of this window.  A new window will open up and you will see Linux boot up in this window.  You will automatically be logged into this Linux virtual machine when it is booted.


=== Get Started with a Simple Experiment ===

1. You will be automatically logged into the GENI-in-a-Box virtual machine when it starts up.   Open up a terminal window by clicking on the icon for a terminal on top of the screen.

2. In the terminal window, use Omni to list the aggregates available to you using the command {{{omni.py listaggregates}}}.   You should see something like this in your terminal window:
{{{
$ omni.py listaggregates
INFO:omni:Loading config file /home/gibuser/.gcf/omni_config
INFO:omni:Using control framework gib_ch
INFO:omni:Listing 1 aggregates...
INFO:omni:  Aggregate 1:
urn:publicid:IDN+geni:gpo:gcf:am1+authority+am 
http://geni-in-a-box.net:8001
INFO:omni: ------------------------------------------------------------
INFO:omni: Completed listaggregates:

    Options as run:
                framework: gib_ch
		getversionCacheName: /home/gibuser/.gcf/get_version_cache.json

    Args: listaggregates

    Result Summary: Found 1 aggregate. URN: urn:publicid:IDN+geni:gpo:gcf:am1+authority+am; URL: http://geni-in-a-box.net:8001 
INFO:omni: ============================================================
$ 
}}}

Look at the Result Summary from Omni.  You'll see that Omni found one aggregate available to you at URL {{{http://geni-in-a-box.net:8001}}}.  This is the aggregate you will use to run your experiments.

3. Now, let's find out the resources advertised by this aggregate using the command {{{omni.py -a http://geni-in-a-box.net:8001 listresources}}}:
{{{
$ omni.py -a http://geni-in-a-box.net:8001 listresources
INFO:omni:Loading config file /home/gibuser/.gcf/omni_config
INFO:omni:Using control framework gib_ch
INFO:omni:Listed resources on 1 out of 1 possible aggregates.
INFO:omni:<?xml version="1.0" ?>
INFO:omni:  <!-- Resources at AM:
	URN: unspecified_AM_URN
	URL: http://geni-in-a-box.net:8001
 -->
INFO:omni:  <!-- Resources at AM:
	URN: urn:publicid:IDN+geni-in-a-box.net+authority+cm
	URL: http://localhost:8001
 --><rspec expires="2013-08-20T22:26:14Z" generated="2012-07-16T22:26:14Z" type="advertisement" xmlns="http://www.protogeni.net/resources/rspec/2" xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.protogeni.net/resources/rspec/2 http://www.protogeni.net/resources/rspec/2/ad.xsd ">      
      <node component_id="urn:publicid:IDN+geni-in-a-box.net+node+pc101" component_manager_id="urn:publicid:IDN+geni-in-a-box.net+authority+cm" component_name="pc101" exclusive="true">            
              <hardware_type name="openVZ container">                  
              </hardware_type>            
              <sliver_type name="virtual-pc">                  
                  <disk_image description="Standard 32-bit Fedora 15 image" name="urn:publicid:IDN+geni-in-a-box.net+image:FEDORA15-STD" os="Fedora" version="15"/>                  
                  <disk_image default="true" description="Standard 32-bit Fedora 15 image" name="urn:publicid:IDN+geni-in-a-box.net+image:FEDORA15-STD" os="Fedora" version="15"/>                  
              </sliver_type>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth0" role="control">                  
                      <emulab:interface name="eth0"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth1" role="experimental">                  
                      <emulab:interface name="eth2"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth2" role="experimental">                  
                      <emulab:interface name="eth3"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth3" role="experimental">                  
                      <emulab:interface name="eth1"/>                  
              </interface>        
              <location country="Molvania"/>            
      </node>      
      
      ... 

      <node component_id="urn:publicid:IDN+geni-in-a-box.net+node+pc106" component_manager_id="urn:publicid:IDN+geni-in-a-box.net+authority+cm" component_name="pc106" exclusive="true">            
              <hardware_type name="openVZ container">                  
              </hardware_type>            
              <sliver_type name="virtual-pc">                  
                  <disk_image description="Standard 32-bit Fedora 15 image" name="urn:publicid:IDN+geni-in-a-box.net+image:FEDORA15-STD" os="Fedora" version="15"/>                  
                  <disk_image default="true" description="Standard 32-bit Fedora 15 image" name="urn:publicid:IDN+geni-in-a-box.net+image:FEDORA15-STD" os="Fedora" version="15"/>                  
              </sliver_type>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc106:eth0" role="control">                  
                      <emulab:interface name="eth0"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc106:eth1" role="experimental">                  
                      <emulab:interface name="eth2"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc106:eth2" role="experimental">                  
                      <emulab:interface name="eth3"/>                  
              </interface>            
              <interface component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc106:eth3" role="experimental">                  
                      <emulab:interface name="eth1"/>                  
              </interface>        
              <location country="Molvania"/>            
      </node>      
</rspec>
INFO:omni: ------------------------------------------------------------
INFO:omni: Completed listresources:

  Options as run:
		aggregate: ['http://geni-in-a-box.net:8001']
		framework: gib_ch
		getversionCacheName: /home/gibuser/.gcf/get_version_cache.json

  Args: listresources

  Result Summary: Queried resources from 1 of 1 aggregate(s).
 
INFO:omni: ============================================================
$ 
}}}
The output of the command is the ''advertisement Rspec'' from the GENI-in-a-Box aggregate.  You'll see the aggregate advertises six compute resources.   Only two are shown here for readability reasons but you will find the complete advertisement rspec [attachment:gib-advert.rspec here].  Look at the description of the first resource in the spec.   This compute resources is an openVZ container running Fedora 15 image (or an Ubuntu 10 image if you are using the Ubuntu flavor of GENI-in-a-Box).  The  resource has four network interfaces: {{{eth0}}} through {{{eth3}}}.  {{{eth0}}} is a control interface and is not available to the experimenter.  All six compute resources advertised by this aggregate are identical.  You can therefore use this aggregate to create experiment topologies with up to six nodes and up to three links per node. 

4. We are now ready to run an experiment using these resources.  We'll start with a very simple experiment that consists of two hosts connected to one another by a single link.   When the hosts come up they execute an experimenter specified script that:
    * Downloads and installs iperf on each host.
    * Runs iperf in server mode on the host named 'left' and iperf in client mode on the host named 'right'.  The outputs of the iperf commands are written to /tmp/iperf-srv.log and /tmp/iperf-client.log on the respective hosts.
We will ssh into these hosts to view these logs.

The request rspec for this experiment (and other examples of request rspecs) are in the directory {{{~/geni-in-a-box}}}.
{{{
$ cd geni-in-a-box
$ ls
click-example.rspec  four-nodes.rspec       islands.rspec  README.txt             two-nodes-iperf.rspec
example-scripts      install-example.rspec  out.log        three-nodes-lan.rspec
}}}
We'll use the spec file called two-nodes-iperf.rspec.  You can view it [attachment:two-nodes-iperf.rspec here] or inside the VM.  This rspec requests two nodes called left and right, each of which has one network interface called left:if0 on node left and right:if0 on node right.  The {{{<install>}}} element in the rspec asks the aggregate to download a [attachment:iperf-execute-script.sh script] from the specified URL, uncompress and untar it,  and save it in the /local directory.  The <execute> element asks the aggregate to execute the specified script when the hosts come up.  In this case the script to be executed is the one that was installed in /local.



= EXTRA!!! =

3. Now, let's find out the GENI AM API version and GENI Rspecs version supported by this aggregate using the command {{{omni.py -a http://geni-in-a-box.net:8001 get version}}}:
{{{
$omni.py  -a http://geni-in-a-box.net:8001 getversion
INFO:omni:Loading config file /home/gibuser/.gcf/omni_config
INFO:omni:Using control framework gib_ch
INFO:omni:AM URN: unspecified_AM_URN (url: http://geni-in-a-box.net:8001) has version:
INFO:omni:{   'geni_ad_rspec_versions': [   {   'extensions': [],
                                      'namespace': 'http://www.geni.net/resources/rspec/3',
                                      'schema': 'http://www.geni.net/resources/rspec/3/ad.xsd',
                                      'type': 'geni',
                                      'version': '3'}],
    'geni_api': 2,
    'geni_api_versions': {   '2': 'https://127.0.0.1:8001/'},
    'geni_request_rspec_versions': [   {   'extensions': [],
                                           'namespace': 'http://www.geni.net/resources/rspec/3',
                                           'schema': 'http://www.geni.net/resources/rspec/3/request.xsd',
                                           'type': 'geni',
                                           'version': '3'}]}
INFO:omni: ------------------------------------------------------------
INFO:omni: Completed getversion:

  Options as run:
		aggregate: ['http://geni-in-a-box.net:8001']
		framework: gib_ch
		getversionCacheName: /home/gibuser/.gcf/get_version_cache.json
		noGetVersionCache: True

  Args: getversion

  Result Summary: 
Got version for http://geni-in-a-box.net:8001
 
INFO:omni: ============================================================
$ 
}}}

The results of this command tell you that the GENI-in-a-Box aggregate manager implements the GENI AM API version 2 and GENI Rspecs version 3. 


2. In the terminal window, cd to the directory geni-in-a-box in your home directory and list the contents of that directory.  You will see a number of 
    
3. List the contents of the directory (ls).  You will see a number of example request rspec files you can use to get started.  We'll walk you through an experiment using one of these rspecs in section [wiki:sampleExperiment].

4. Before you try running an experiment verify everything is set up right.  Use the http://trac.gpolab.bbn.com/gcf/wiki/Omni omni] experiment tool to list the aggregates available to you: omni.py listaggregates.  This command lists the aggregates registered with the slice authority that ships with GENI-in-a-Box.  You should see one aggregate listed:

5. Check the version of the GENI AM API implemented by this aggregate: omni.py --