Version 31 (modified by 12 years ago) (diff) | ,
---|
Table of Contents
Using GENI-in-a-Box
This page describes how to install and use GENI-in-a-Box on your computer.
1 Install GENI-in-a-Box
Please make sure you have VirtualBox Version 4.1.16 or later installed on your computer.
- Start up VirtualBox and from the VirtualBox "File" menu, select "Import Appliance...".
- 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.
- 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.
2 Get Started with a Simple Experiment
2.1 Discover Resources
We start by finding out the aggregates available to us inside GENI-in-a-Box and learning about the resources advertised by these aggregates:
- After you are logged into the GENI-in-a-Box virtual machine, open up a terminal window by clicking on the icon for a terminal on top of the screen.
- 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.
- 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 here. Look at the description of the first resource in the rspec. 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.
2.2 Acquire and Configure Resources
Before we run an experiment we need to acquire the resources needed the experiment. Our introductory experiment will consist of two hosts connected to one another by a single link. When the hosts come up they execute a script provided by us that:
- Downloads and installs iperf on each host.
- Runs iperf in server mode on one host and and in client mode on the other host. The outputs of the iperf commands are written to /tmp/iperf-server.log and /tmp/iperf-client.log on the respective hosts.
As a part of this experiment 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 rspec file called two-nodes-iperf.rspec. You can view it here or inside the VM. This rspec requests two hosts called left
and right
. Host left
has one interface called left:if0
and host right
has one interface called right:if0
. The two interfaces are connected by a link called left-right-lan
. The <install>
element in the rspec asks the GENI-in-a-Box aggregate manager to download a 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
.
The following steps will walk us through acquiring the resources for our experiment:
- First we need to create a slice using the command
omni.py createslice myslice
wheremyslice
is the name or our slice (of course you can give your slice some other name).$ omni.py createslice myslice INFO:omni:Loading config file /home/gibuser/.gcf/omni_config INFO:omni:Using control framework gib_ch INFO:omni:Created slice with Name myslice, URN urn:publicid:IDN+geni:gpo:gcf+slice+myslice, Expiration 2012-09-28 23:49:43 INFO:omni: ------------------------------------------------------------ INFO:omni: Completed createslice: Options as run: framework: gib_ch getversionCacheName: /home/gibuser/.gcf/get_version_cache.json Args: createslice myslice Result Summary: Created slice with Name myslice, URN urn:publicid:IDN+geni:gpo:gcf+slice+myslice, Expiration 2012-09-28 23:49:43 INFO:omni: ============================================================ $
- We now send our request rspec to the GENI-in-a-Box aggregate manager using the command
omni.py -a http://geni-in-a-box.net:8001 createsliver myslice two-nodes-iperf.rspec
. This command will take many minutes to complete because it configures and boots up the requested virtual machines; does some additional configuration; and download, installs, and runs iperf. If our request is successful, the aggregate manager will allocate the requested resources to our slice. In GENI parlance the resources allocated to our slice are called slivers. Thecreatesliver
request returns a manifest spec that provides details of the resources allocated to us. The following is a snippet of the manifest your will get back fromcreatesliver
:$ omni.py --api-version 2 -a http://geni-in-a-box.net:8001 createsliver myslice two-nodes-iperf.rspec INFO:omni:Loading config file /home/gibuser/.gcf/omni_config INFO:omni:Using control framework gib_ch WARNING:omni:Slice urn:publicid:IDN+geni:gpo:gcf+slice+myslice expires in <= 3 hours INFO:omni:Slice urn:publicid:IDN+geni:gpo:gcf+slice+myslice expires on 2012-10-02 16:32:42 UTC INFO:omni:Creating sliver(s) from rspec file two-nodes-iperf.rspec for slice urn:publicid:IDN+geni:gpo:gcf+slice+myslice INFO:omni:Got return from CreateSliver for slice myslice at http://geni-in-a-box.net:8001: INFO:omni:<?xml version="1.0" ?> INFO:omni: <!-- Reserved resources for: Slice: myslice at AM: URN: unspecified_AM_URN URL: http://geni-in-a-box.net:8001 --> INFO:omni: <rspec generated="2012-09-11T16:29:16Z" generated_by="Flack" type="manifest"> <node client_id="left" 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" exclusive="false" sliver_id="urn:publicid:IDN+geni-in-a-box.net+sliver+101"> <sliver_type name="virtual-pc"> <disk_image name="urn:publicid:geni-in-a-box.net+image//FEDORA15-STD"/> </sliver_type> <services> <install file_type="tar.gz" install_path="/local" url="http://groups.geni.net/geni/attachment/wiki/GiB-gettingStarted/iperf-execute-script.tar.gz?format=raw"/> <execute command="/local/iperf-execute-script.sh" shell="sh"/> <login authentication="ssh-keys" hostname="pc101.geni-in-a-box.net" port="22" username="alice"/> </services> <interface client_id="left:if0" component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth1" mac_address="00:0C:29:B4:DF:A7" sliver_id="urn:publicid:IDN+geni-in-a-box.net+sliver+1011"> <ip address="10.0.3.101"/> </interface> <rs:vnode name="pc101" xmlns:rs="http://www.protogeni.net/resources/rspec/ext/emulab/1"/> <host name="pc101.geni-in-a-box.net"/> </node> ... <link client_id="left-right-lan"> <component_manager name="urn:publicid:IDN+geni-in-a-box.net+authority+cm"/> <interface_ref client_id="left:if0" component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth1" sliver_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc101:eth1"/> <interface_ref client_id="right:if0" component_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc102:eth1" sliver_id="urn:publicid:IDN+geni-in-a-box.net+interface+pc102:eth1"/> <property dest_id="right:if0" source_id="left:if0"/> <property dest_id="left:if0" source_id="right:if0"/> <link_type name="lan"/> </link> </rspec> INFO:omni: ------------------------------------------------------------ INFO:omni: Completed createsliver: Options as run: aggregate: ['http://geni-in-a-box.net:8001'] framework: gib_ch getversionCacheName: /home/gibuser/.gcf/get_version_cache.json Args: createsliver myslice two-nodes-iperf.rspec Result Summary: Got Reserved resources RSpec from geni-in-a-box-net-8001 INFO:omni: ============================================================ $
Notice the manifest rspec is essentially your request respec annotated with information about the resources that got allocated to you. For example, the <node>
element of the manifest includes the MAC and IP addresses assigned to each network interface on the node (host) and information you will need to ssh into the nodes (e.g. the fully qualified domain name of the host ).
2.3 Using your Resources
You can now ssh into the hosts allocated to you and do what you need to do to get your experiment working. For example, you can install and run software. If needed, you can use the {{sudo}} command to do things that require root privileges.
In the case of our experiment, the software needed (iperf) was installed by our startup script. Our startup script put the output of iperf in a file accessible from a web browser. Since our iperf client ran on node pc101
(the node labeled 'left' in the request spec), we can use a browser to view the output of this client. Start up Firefox in a terminal on the GENI-in-a-Box virtual machine and enter the url http://pc101.geni-in-a-box.net/iperf-client.log
. The iperf client output should appear in your browser window.
You can also ssh into the node pc102 to view this file. GENI-in-a-Box comes with a user account 'alice' with private and public keys for alice installed in it. When experimenter nodes are created an account is created for alice on these nodes and alice's public key installed in the .ssh directory inside alice's home directory. You can create your own user accounts; see this page for instructions.
You can ssh into node pc101
as alice type ssh -lalice pc101.geni-in-a-box.net
or just ssh -lalice pc101
. The terminal session below shows the ssh'ing into pc101
, going to the directory with the iperf log file, and viewing that file. The password for alice can be found in ~/.gcf/passwords
.
$ ssh -lalice pc101 The authenticity of host 'pc101 (10.0.1.101)' can't be established. RSA key fingerprint is d1:ea:fe:92:38:69:6b:85:3e:7c:65:cb:83:26:f5:0a. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'pc101,10.0.1.101' (RSA) to the list of known hosts. alice@pc101's password: [alice@left ~] $ cd /var/www/html [alice@left html] $ ls iperf-client.log [alice@left html] $ cat iperf-client.log ------------------------------------------------------------ Server listening on TCP port 5001 TCP window size: 85.3 KByte (default) ------------------------------------------------------------ [ 4] local 10.0.3.101 port 5001 connected with 10.0.3.102 port 53488 [ ID] Interval Transfer Bandwidth [ 4] 0.0-10.1 sec 50.1 MBytes 41.6 Mbits/sec [alice@left html] $
2.4. Freeing up Resources
When you are done with your experiment you can return the resources allocated to you using omni's deletesliver
command:
$ omni.py -a http://geni-in-a-box.net:8001 deletesliver myslice INFO:omni:Loading config file /home/gibuser/.gcf/omni_config INFO:omni:Using control framework gib_ch WARNING:omni:Slice urn:publicid:IDN+geni:gpo:gcf+slice+myslice expires in <= 3 hours INFO:omni:Slice urn:publicid:IDN+geni:gpo:gcf+slice+myslice expires on 2012-10-02 21:55:17 UTC INFO:omni:Deleted sliver urn:publicid:IDN+geni:gpo:gcf+slice+myslice on unspecified_AM_URN at http://geni-in-a-box.net:8001 INFO:omni: ------------------------------------------------------------ INFO:omni: Completed deletesliver: Options as run: aggregate: ['http://geni-in-a-box.net:8001'] framework: gib_ch getversionCacheName: /home/gibuser/.gcf/get_version_cache.json Args: deletesliver myslice Result Summary: Deleted sliver urn:publicid:IDN+geni:gpo:gcf+slice+myslice on unspecified_AM_URN at http://geni-in-a-box.net:8001 INFO:omni: ============================================================ $
Congratulations! You have successfully run an experiment using GENI-in-a-Box resources!
2.4 GENI-in-a-Box Tips
See this page for tips that you might find helpful while using GENI-in-a-Box.
3. What's Next?
You are now ready to run your own experiments inside GENI-in-a-Box. You might want to start with one of the sample rspecs in the ~/geni-in-a-box
directory and edit it as needed by your experiment. See the README
file in this directory for a description of the rspecs in this directory.
You can apply for a GENI account and use real GENI aggregates and resources for your experiments. See GiB-to-ProtoGENI for tips on moving your experiment from GENI-in-a-Box to other aggregates (and vice versa).
MOVE OUT
- 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.