wiki:DICLOUD/GEC12tutorial

Version 47 (modified by David Irwin, 12 years ago) (diff)

--

DiCloud Tutorial at GEC12

This page summarizes the DiCloud tutorial from GEC 12. Slides can be found here.

Tutorial sections:

  • Tutorial: Pre-requisites
  • Setup: Install dependent software packages
  • Setup: Configure DiCloud's MySQL database
  • Setup: Create Amazon user credentials
  • Setup: Register new user on Amazon EC2
  • Setup: Configure environment variables
  • Tutorial: Configuring Amazon for tutorial participants
  • Tutorial: Running the DiCloud server
  • Tutorial: Using the DiCloud console
  • Tutorial: Using the DiCloud web portal
  • Setup: Configuring Gush
  • Tutorial: Running a Gush experiment using DiCloud and Orca

The sections labeled as Setup have already been performed on each tutorial participants' VM image, and can be skipped by tutorial participants. Directions on how the tutorial image for GEC12 was setup are also available here. We provide them here as an example of how to setup an independent DiCloud deployment from scratch. Note that the setup assumes a user geni exists, and that all DiCloud files (from here) are located in the directory ~/Tutorials/DiCloud.

Tutorial: Pre-requisites

  1. Install VirtualBox: Download the latest VirtualBox software. If you already have VirtualBox installed on your machine, make sure it is version 4.08 or above.

Note to Ubuntu users: The version of VirtualBox distributed with Ubuntu 10.04 is old. Download the latest version from here.

  1. Download VirtualBox VM image: Download the VirtualBox VM image (GEC12-Tutorials-Final.ova) needed for the DiCloud tutorial from here. A README with a copy of these instructions is also available at the same location.
  1. Install the gec12-tutorials-final.ova image: Start up VirtualBox, select File->Import Appliance..., and follow the instructions. Accept the default VM settings during the import. To run the virtual machine, go to the Oracle VM VirtualBox Manager window, select the virtual machine gec12-tutorial-final and click the green arrow labeled Start at the top of this window.

If the install was successful, you should see the logon screen for the Ubuntu OS. Passwords for logging into the VM will be handed out at the tutorial.

  1. Turn off the VM: Turn off the virtual machine by clicking on the power button icon on the bottom right of the screen.
  1. Note that this release of tutorial software is intended for use at the GEC12 tutorial only. In particular, these directions are for Ubuntu 10.04.3 LTS (Lucid Lynx). To find out your version of Ubuntu, open a terminal and run:
$ cat /etc/issue
Ubuntu 10.04.3 LTS \n \l

Setup: Install dependent software packages

To install dependent software you need root access. The directions assume the user is able to use sudo to run commands as root. The VM image provided to tutorial participants is pre-configured to allow the geni user to execute sudo. We also assume that the directory ~/Tutorials/DiCloud exists, and the files referenced above have been untar'ed into that directory. To create the directory run mkdir -p ~/Tutorials/DiCloud. Then untar dicloud-tutorial.tgz into the directory, as shown below.

$ mkdir -p ~/Tutorials/DiCloud
$ cd ~/Tutorials
$ tar xzvf ~/dicloud-tutorial.tgz
$ sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
$ sudo apt-get update
$ sudo apt-get install keychain
$ sudo apt-get install sun-java6-jdk
$ sudo apt-get install maven2
$ sudo apt-get install apache2
$ sudo apt-get install libapache2-mod-php5
$ sudo apt-get install php5-mysql
$ sudo a2enmod php5
$ sudo apt-get install mysql-server

MySQL server will ask you to set a root password. Remember the password.

We need to sym-link apache's /var/www directory to ~/Tutorials/DiCloud/www to make the web portal available, and change the permissions of ~/Tutorials/DiCloud/www to be owned by www-data (the apache user).

$ sudo su
$ su www-data
$ cd /var/www
$ ln -s /home/geni/Tutorials/DiCloud/www/vise vise
$ exit
$ exit
$ cd ~/Tutorials/DiCloud
$ chown -R www-data www
$ chgrp -R www-data www

Finally, we create sym-links to all the keys in the top-level directory to reduce the typing we must do in the console.

sudo ln -s /home/geni/Tutorials/DiCloud/ec2/keys/geni_cert.pem /geni_cert.pem
sudo ln -s /home/geni/Tutorials/DiCloud/ec2/keys/geni_pk.pem /geni_pk.pem
sudo ln -s /home/geni/Tutorials/DiCloud/ec2/keys/geni_cert_web.pem /geni_cert_web.pem
sudo ln -s /home/geni/Tutorials/DiCloud/ec2/keys/geni_pk_web.pem /geni_pk_web.pem
sudo ln -s /home/geni/Tutorials/DiCloud/ec2/keys/geni-keypair.pem /geni-keypair.pem

Setup: Configure DiCloud's MySQL Server

First, log into MySQL and create the dicloud database by running the following commands.

$ mysql -u root -p
$ mysql> create database dicloud;
$ mysql> quit;

Next load the DiCloud schema, create an admin user, and give the user database rights

$ cd ~/Tutorials/DiCloud
$ mysql -u root -p < dicloud.schema
$ mysql -u root -p
$ mysql> INSERT INTO users(id, username, password) VALUES (1, 'admin', SHA1('geni'));
$ mysql> INSERT INTO admin_rights VALUES (1, true, true, true, true);
$ mysql> create user vise;
$ mysql> SET PASSWORD FOR 'vise' = PASSWORD('');
$ mysql> GRANT ALL ON dicloud.* TO 'vise'@'localhost';

Setup: Create Amazon user credentials

Amazon EC2 requires that each user create and upload an X.509 certificate to Amazon, and use the corresponding private key to access the web services functions. We create the certificate and private key below. We also create a public/private RSA keypair to access any VMs we create using ssh.

$ cd ~/Tutorials/DiCloud/ec2/keys
$ openssl genrsa 1024 > ./geni_pk.pem
$ openssl req -new -x509 -nodes -sha1 -key ./geni_pk.pem > ./geni_cert.pem
$ ssh-keygen geni-keypair.pem

Setup: Register new user on Amazon EC2

  • Create an account with Amazon web services by going here and clicking on "Create an AWS Account" in the upper-right portion of the page. Follow Amazon's directions for creating an account. Amazon requires that the account link to a valid credit card for payment.
  • Once you've created an account go back to here and click on "Sign in to the AWS Management Console" in the upper-right portion of the page. Once logged in, click on the AWS IAM tab (second from the right). Click on "Users" on the left panel, and then click "Create New Users". Create a user named "geni".
  • Next click on the geni user, and go to the "Security Credentials" tab at the bottom of the page. Here you need to generate Access Keys and download the credentials.csv file that has the Access Key ID and the Secret Access Key. Also, upload the signing certificate we created at ~/Tutorials/DiCloud/ec2/keys/geni_cert.pem. Finally, click on the "Amazon EC2" tab (third from the left). Then click on the "Key Pairs" link at the bottom of the left panel. Now click "Import Key Pair". Give the new keypair the name "geni-keypair" and copy in the contents of ~/Tutorials/DiCloud/ec2/keys/geni-keypair.pem. Copy the credentials file credentials.csv to ~/Tutorials/DiCloud/ec2/keys/ and create the file ~/Tutorials/DiCloud/ec2/keys/geni_aws_credentials.txt, which should look as follows:
$ cat geni_aws_credentials.txt
AWSAccessKeyId=<Your Access Key ID here>
AWSSecretKey=<Your Secret Key Here>

Setup: Configure environment variables

We configure environment variables to add references to the access key id and secret access key as environment variables. We also create copies of the keys and make them accessible to the DiCloud web portal, which uses apache2. Finally, we add references to the access key id and secret key to an S3 configuration file.

$ cd ~/Tutorials/DiCloud
$ nano environment

[ Insert correct values from geni_aws_credentials.txt
    AWS_ACCESS_KEY_ID=
    AWS_SECRET_ACCESS_KEY= ]

$ cat environment >> ~/.bashrc
$ cd ~/Tutorials/DiCloud/ec2/keys
$ cp ./geni_pk.pem ./geni_pk_web.pem
$ sudo chown www-data geni_pk_web.pem
$ sudo chgrp www-data geni_pk_web.pem
$ cp ./geni_cert.pem ./geni_cert_web.pem
$ sudo chown www-data geni_cert_web.pem
$ sudo chgrp www-data geni_cert_web.pem

Add Access Key Id and Secret Access Key to .s3cfg file. Copy .s3cfg file to ~geni/.

$ nano ~/Tutorials/DiCloud/.s3cfg
  
  [ 
    Modify lines specifying access_key and secret_key:
 
       access_key = xxx
       secret_key = xxx
  ]

$ cp ~/Tutorials/DiCloud/.s3cfg ~/.s3cfg

Tutorial: Configuring Amazon for Tutorial Participants

Tutorial participants should download their certificate, private key, key pair, credential.csv, and geni_aws_credentials.txt files by performing the following commands.

$ cd ~/Tutorials/DiCloud/
$ ./key_install geni.cs.umass.edu

Tutorial: Run the DiCloud server

$ cd ~/Tutorials/DiCloud/dicloud/bin
$ ./dicloud_server.sh

Tutorial: Using the DiCloud console

Open a new terminal. We run ntpdate to make sure the time is accurate. Amazon will fail calls from machines with inaccurate local time. Also, note that we will use the Amazon Machine Image ami-013d6c44 for all VMs in the us-west-1 region. This is a basic VM image that runs a 32-bit version of Debian Linux. Amazon has thousands of images available for use, including Windows images.

$ sudo ntpdate ntp.ubuntu.com
$ cd ~/Tutorials/DiCloud/dicloud/bin
$ ./dicloud_console.sh
dicloud - not connected>connect localhost 1099
Connecting to //localhost:1099/dicloud/server
dicloud - //localhost:1099>ec2 start /geni_cert.pem /geni_pk.pem ami-013d6c44 1 m1.small us-west-1 geni-keypair
dicloud - //localhost:1099>help
Commands available for the main menu are:
add credit amount_of_money
   Add credit to the AWS account
billing history history_size csv|html
   Get the AWS account activity history in CSV or HTML format (a history of 0 retrie$
connect DiCloudServerHostName RmiPortNumber
   Connects to the DiCloud server
ebs attach cert.pem pk.pem ec2_region ebs_volume_id ec2_instance_id device_name
   Attach an EBS volume (ebs_volume_id) to the running instance (ec2_instance_id) as$
ebs create cert.pem pk.pem size_in_gb ec2_region ec2_availability_zone
   Create an EBS volume
ebs delete cert.pem pk.pem volume_id ec2_region
   Delete an EBS volume
ebs detach cert.pem pk.pem ec2_region ebs_volume_id
   Detach EBS volume ebs_volume_id from its EC2 instance
ebs probe cert.pem pk.pem volume_id ec2_region ascii|html
   Probe an EBS volume and get current status information
ec2 probe cert.pem pk.pem instance_id ec2_region html|ascii
   Check the status of a running EC2 instance
ec2 start cert.pem pk.pem ami_id instance_nb instance_type ec2_region ec2_keypair_na$
   Start a new EC2 instance
ec2 stop cert.pem pk.pem instance_id ec2_region ec2_keypair_name
   Stop an EC2 instance
get balance
   Get the AWS account balance
help
   Print this help message
history [<command index>]
   Display history of commands for the console.
quit
   Quit the console
s3 create bucket_name region
   Create an S3 bucket
s3 delete bucket_name region
   Delete an S3 bucket
s3 get s3_bucket_name object_name file_path
   Get the content of an object named object_name into the specified file from the S$
s3 probe bucket_name region
   Get information about an S3 bucket
s3 put s3_bucket_name object_name file_path
   Put the content of the specified file in an object named object_name in the S3 bu$
shutdown
   Shutdown the DiCloud server the console is currently connected to.
dicloud - //localhost:1099>get balance
Current balance is: $99.53222835338767
dicloud - //localhost:1099>ec2 probe /geni_cert.pem /geni_pk.pem i-b87b74d8 us-west-1 ascii
Instance Id: i-b87b74d8
AMI Id: ami-7f418316
Public name: ec2-75-101-245-135.compute-1.amazonaws.com
Private name: ip-10-244-46-161.ec2.internal
Public IP: 75.101.245.135
Private IP: 10.244.46.161
Instance State: running
Instance Type: m1.small
Key pair: geni-keypair
Start time: 2011-10-17T17:31:41+0000
Availability zone: us-west-1b
dicloud - //localhost:1099>quit

You can also script the DiCloud console. An example is below.

$ echo "connect localhost 1099
get balance
quit" > ./getbalance.txt
$ ./dicloud_console_script.sh -silent < ./getbalance.txt

Example use of S3

dicloud - //localhost:1099>s3 create gec12-tutorial-1 us
dicloud - //localhost:1099>s3 put gec12-tutorial-1 test /home/geni/Tutorials/DiCloud/s3_test
Uploading file /home/geni/Tutorials/DiCloud/s3_test as object test in bucket gec12-tutorial-1
dicloud - //localhost:1099>s3 get gec12-tutorial-1 test /home/geni/Tutorials/DiCloud/test
Downloading file /home/geni/Tutorials/DiCloud/test from object test in bucket gec12-tutorial-1dicloud - //localhost:1099>
dicloud - //localhost:1099>s3 delete gec12-tutorial-1 us

Example use of EBS

dicloud - //localhost:1099>ebs create /geni_cert.pem /geni_pk.pem 1 us-west us-west-1b
dicloud - //localhost:1099>ebs delete /geni_cert.pem /geni_pk.pem <volume_id> us-west

Tutorial: Using the DiCloud web portal

Go to http://localhost/vise/dicloud.

The user guide for the DiCloud web portal is available here.

First we log in as user 'admin' with password 'geni'. We can then create non-administrative user. We will create a user 'geni' with password 'geniuser' that does not have administrative permissions. We will then log out and log back in as this user.

Setup: Configuring Gush

Directions adapted from http://groups.geni.net/geni/wiki/GEC11VMSetup under installing Gush.

$ apt-get install keychain
$ mkdir /usr/local/geni/gush
$ cd /usr/local/geni/gush
$ wget http://gush.cs.williams.edu/gush-bin-32bit.tgz
$ cd ~
$ bash
$ cp ~/Tutorials/DiCloud/ec2/keys/geni-keypair.pem ~/.ssh/id_rsa
$ cp ~/Tutorials/DiCloud/ec2/keys/geni-keypair.pub ~/.ssh/id_rsa.pub
$ keychain ~/.ssh/id_rsa
$ echo 'StrictHostKeyChecking no' >> ~/.ssh/config
$ mkdir ~/Tutorials/DiCloud/gush
$ cd ~/Tutorials/DiCloud/gush
$ cp /usr/local/geni/gush/gush-bin-32bit.tgz .
$ tar xzvf gush-bin-32bit.tgz

Tutorial: Running a Gush experiment using DiCloud and/or Orca resources

Verify gush works

$ cd ~/Tutorials/DiCloud/gush/
$ cp ~/Tutorials/DiCloud/ec2/keys/geni-keypair.pem ~/.ssh/id_rsa
$ cp ~/Tutorials/DiCloud/ec2/keys/geni-keypair.pub ~/.ssh/id_rsa.pub
$ keychain ~/.ssh/id_rsa
$ ./gush -P 15000

Now we are going to follow along an example adapted from the Gush web page here.

We will walk through a simple example that shows how Gush uses our Amazon resources. This example will copy a tarball to 2 Linux hosts, untar it, and then cat the file included. This simple application goes over the basic building blocks needed to manage applications using Gush.

The following files are needed to run this application and are described below. They must be modified slightly (look for machine names and user names) to run on your machines.

  • simple.xml
  • directory.xml
  • gush.prefs
  • software.tar (includes software.txt, which consists of 1 line of text that says "Hello World")

Application Description: simple.xml

simple.xml is a Gush application description file. At the highest level, we define the project, which in this case is called "simple." Next we define any software packages that are needed. Gush application descriptions are comprised of different types of "blocks."

<?xml version="1.0" encoding="utf-8"?>
<gush>
  <project name="simple">
    <software name="SimpleSoftwareName" type="none">
      <package name="Package" type="web">
        <path>http://geni.cs.umass.edu/software.tar</path>   //Software tarball
        <dest_path>software.tar</dest_path>
      </package>
    </software>
    <component name="Cluster1">
      <rspec>
        <num_hosts>2</num_hosts>                                           //Number of remote clients
      </rspec>
      <software name="SimpleSoftwareName" />
      <resources>
        <resource type="ssh" group="local"/>
      </resources>
    </component>
    <experiment name="simple">
      <execution>
        <component_block name="cb1">
  	  <component name="Cluster1" />
	  <process_block name="p2">  
  	    <process name="cat">                                        //Define actual execution
	      <path>cat</path>                                          //"cat software.txt"
	      <cmdline>                  
 	        <arg>software.txt</arg>
	      </cmdline>
	      <cwd/>
	    </process>
	  </process_block>
	</component_block>
      </execution>
    </experiment>
  </project>
</gush> 

Environment Configuration: directory.xml

directory.xml defines the Gush resource directory. This file tells the Gush default matcher where to locate resources during execution. In the following example, we specify the IP addresses of the nodes available to us. Replace amazon.machine.ip and amazon.machine2.ip with the IP addresses of the VMs you created earlier.

<?xml version="1.0" encoding="UTF-8"?>
<gush>
    <resource_manager type="ssh">
        <node hostname="amazon.machine.ip:15400" user="root" group="local" />
    </resource_manager>
    <resource_manager type="ssh">
        <node hostname="amazon.machine2.ip:15400" user="root" group="local" />
    </resource_manager>
</gush>

Gush Preferences: gush.prefs

The gush.prefs file defines basic preferences that customize the way applications are run. In this example we specify the ClientPrefix and ClientPath which control how the client is started ({ClientPrefix}/client) and what working directory the client uses when executing commands (chdir {ClientPath}). We can leave UsePlanetLab set to true even though we aren't using PlanetLab in this example.

<preferences>
  <pref key="ClientPrefix">./</pref>
  <pref key="ClientPath">./</pref>
  <pref key="UsePlanetLab">true</pref>
</preferences>

Start Gush

Now we are ready to run our example. First, we need to set the appropriate hostnames on each host. Next, the following shows the output from a run using two clients. You only need to type the commands that appear after "gush>".

$ ssh root@<Amazon IP 1> “hostname <Insert IP 1>”
$ ssh root@<Amazon IP 2> “hostname <Insert IP 2>”
$ ./gush -P 15000
gush> 
gush> info nodes
There are 2 known nodes:
[   U       ] root@amazon.machine.ip:15400(pref=0) (Disconnected.)
[   U       ] root@amazon.machine2.ip:15400(pref=0) (Disconnected.)
gush> 
gush> load tests/simple-ssh.xml 
Project "simple" is selected.
Experiment "simple" is selected.
gush> 
gush> run
Starting experiment run.
Running experiment simple...
gush> The configuration matcher has finished matching.
The resource allocator has finished successfully.
root@amazon.machine.ip:15400 has joined the mesh.
The file transfer of Package to amazon.machine.ip has been completed.
The software installation of Package on amazon.machine.ip was successful.
root@amazon.machine2.ip:15400 has joined the mesh.
The file transfer of Package to amazon.machine2.ip has been completed.
The software installation of Package on amazon.machine2.ip was successful.
root@amazon.machine.ip:15400,26347: Hello World

root@amazon.machine2.ip:15400,18302: Hello World

The experiment has ended.

gush> disconnect
gush> root@amazon.machine.ip:15400 has decided to leave the mesh.
root@amazon.machine2.ip:15400 has decided to leave the mesh.

gush> quit

Attachments (3)