Eucalyptus User's Guide (1.4)

This guide is meant for people interested in using an existing installation of Eucalyptus. (If you have a cluster that you would like to install Eucalyptus on, then take a look at the Administrator's Guide first.)

Getting Started Using Eucalyptus (1.4)

We will guide you through getting access to a Eucalyptus-based cloud, as well as installing and using tools for controlling virtual instances. Those familiar with Amazon's EC2 system will find most of these instructions familiar because Eucalyptus can be used with EC2's command-line tools.

If you are using the Eucalyptus Public Cloud, use mayhem9.cs.ucsb.edu instead of your.cloud.server.

Load in your browser the Web page of the Eucalyptus cloud installation that you would like to use. Ask your system administrator for the URL if you don't know it. (The URL will be of the form https://your.cloud.server:8443/, where your.cloud.server is likely to be the front-end of the cluster.)

Click the "Apply" link and fill out the form presented to you. You may not be able to use the system until the (human) administrator receives the notification of your application and approves it. The more information you supply the easier it may be for the administrator to make the decision.

Load the confirmation URL that you receive in the approval email message from the cloud administrator. Log in to the system with the login and password that you chose when filling out the application form.

2. Obtain Credentials ¶

Once you have logged in, you will see the 'Generate Certificate' button under the 'Credentials' tab. Generating a certificate for your account is necessary before you can use Amazon's EC2 command-line tools for querying and controlling Eucalyptus instances. Currently, the Web interface to Eucalyptus is limited and, hence, the use of command-line tools is practically inevitable.

Click the button to generate the certificate and save it. You can keep these keys in a secure place on any host. The following command-line instructions apply to any Unix-flavored machine with bash (not necessarily the cluster where Eucalyptus was installed). (See Amazon's Getting Started Guide for the similar instructions to use under Windows.)

Unzip the keys using the following command and protect them from exposure. The zip-file contains two files with the .pem extension; these are your public and private keys.

mkdir ~/.euca
cd ~/.euca
unzip name-of-the-key-zip.zip
chmod 0700 ~/.euca
chmod 0600 ~/.euca/*

3. Install EC2 command-line tools ¶

Download the EC2 command-line tools from Amazon.

wget http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-30349.zip
unzip ec2-api-tools-1.3-30349.zip

If you are using the Eucalyptus Public Cloud, use mayhem9.cs.ucsb.edu instead of your.cloud.server.

Set the following environment variables and source the 'eucarc' file that came with your credentials to set other crucial Eucalyptus environment variables:

export EC2_HOME=/path/to/installed/ec2-commandline-tools
export PATH=$PATH:$EC2_HOME/bin
source ~/.euca/eucarc

Now you should be ready to start using the tools. To test if the tools work (and if the cloud server is running properly), execute the following EC2 command:

If you get an Invalid timestamp error when running any of the ec2 commands, make sure the clock on your client machine (and the server, if you are in charge of it) is accurate.

ec2-describe-availability-zones

In the output of the above command, you should see the cluster's front-end hostname displayed.

4. Quick Start ¶

Now you can begin running VM instances on the Eucalyptus cloud. Using the EC2 command-line tools, you can learn about installed images, start VM instances using those images, describe the running instances, and terminate them when you're finished with them.

The following EC2 commands will allow you to query the system:

ec2-describe-images
IMAGE <emi-id> ...

ec2-describe-instances
(will be empty until you start an instance, as shown below)

ec2-describe-availability-zones

ec2-describe-keypairs
(will be empty until you add key pairs, as shown below)

Before starting a VM, you need to create at least one key pair. This key pair will be injected into the VM, allowing you to SSH into the instance. Below we will use mykey as a handle, but you may choose any string you like instead:

ec2-add-keypair mykey >mykey.private
('mykey' is the name for the key in Eucalyptus, 'mykey.private' is the file to be used by ssh)

chmod 0600 mykey.private

ec2-run-instances <emi-id> -k mykey -n <number of instances to start>

ec2-describe-instances
(should now show the instance)

If your administrator has configured Eucalyptus to provide security groups and elastic IPs, you may be required to allow logins to your instance, allocate a public IP (if you have not done so before, check 'ec2-describe-addresses' as a reminder), and assign it to your running instance:

Allow 'ssh' connections from the Internet:

ec2-authorize default -P tcp -p 22 -s 0.0.0.0/0

Allocate a public IP if you have not done so already:

ec2-allocate-address

Associate an allocated IP with your running instance:

ec2-associate-address <IP from allocate> -i <instance ID>

Once the instance is shown as 'Running', it will also show two IP addresses assigned to it. You may log into it with the SSH key that you created:

ssh -i mykey.private root@<accessible-instance-ip>

To terminate instances, use:

ec2-terminate-instances <instance-id1> <instance-id2> ... <instance-idn>

Please, see Amazon's EC2 Getting Started Guide for more information about these command-line tools. Keep in mind that, depending on how the administrator has configured Eucalyptus, not all tools/operations are necessarily supported (security groups/elastic IPs). Consult your administrator for more information.

Interacting with Walrus (1.4)

Walrus is a storage service included with Eucalyptus that is interface compatible with Amazon's S3. Walrus allows users to store persistent data, organized as buckets and objects (see Amazon's S3 Getting Started Guide for more information). Walrus system options can be modified via the administrator web interface.

If you would like to use Walrus to manage Eucalyptus VM images, you can use Amazon's tools to store/register/delete them from Walrus.

Otherwise, you may use S3 Curl to interact with Walrus directly. S3 Curl is a command line tool that computes the signature and invokes curl.

You may create, delete, list buckets, put, get, delete objects, set access control policies, etc. Please refer to the Amazon S3 documentation for the S3 interface specification.

You will need the perl-Digest-HMAC package for S3 Curl, if it is not already installed on your system.

You will need to modify the file s3curl.pl in your favorite editor to change the hostname endpoint.

For example, change

my @endpoints = ( 's3.amazonaws.com' );

my @endpoints = ( 'your-host' );

where, your-host is the IP or the hostname on which Walrus runs. For authentication to succeed, it is crucial that your-host is the same as the host portion of the $S3_URL environment variable set by eucarc.

When modifying the file s3curl.pl, please specify just the hostname and not the port number or the entire path (e.g., you would specify xyz.com instead of xyz.com:8773/services/Walrus. However, you need to use the entire path in the command-line when using the tool).

Be sure to source your 'eucarc' file before running the commands below.

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY <curl options>

It is preferable to add your credentials to the ".s3curl" config file. Please read the README file bundled with s3curl for details.

For example, to create a bucket,

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --put /dev/null -- -s -v $S3_URL/bucketName

where bucketName is the name of the bucket that you want to create.

To put an object,

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --put <filename> -- -s -v $S3_URL/bucketName/objectName

where objectName is the name of the object that you want to create.

To get the MD5 checksum, size and last modification time for an object.

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --head -- -s -v $S3_URL/bucketName/objectName > object.head

cat object.head

To get an object

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --get -- -s -v $S3_URL/bucketName/objectName > object

To delete an object,

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --del -- -s -v $S3_URL/bucketName/objectName

To delete a bucket,

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --del -- -s -v $S3_URL/bucketName

Note that, according to the S3 specification, a bucket needs to be empty before it can be deleted.

You may pipe the output through "xmlindent" (you might need to install it, if it is not already installed on your system).

For example, to get the access control policy for a bucket,

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --get -- -s -v $S3_URL/bucketName?acl | xmlindent > bucket.acl

To get the contents of a bucket.

s3curl.pl --id $EC2_ACCESS_KEY --key $EC2_SECRET_KEY --get -- -s -v $S3_URL/bucketName  | xmlindent > bucket.list

To list all buckets for a user.