Eucalyptus User's Guide (1.0

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.)

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.

1. Sign up

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.)

login.png

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.

signup.png

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.

confirm_link.png

2. Generate keys

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.

credentials.png

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. 

$ unzip name-of-the-key-zip.zip
$ mkdir ~/.euca
$ mv euca2-*.pem ~/.euca
$ chmod 0700 ~/.euca
$ chmod 0600 ~/.euca/*.pem

3. Install EC2 command-line tools

Download the EC2 command-line tools from Amazon. 

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

Set the following environment variables (note that the base URL is different from the Web site's URL, both in terms of transport protocol - http instead of https - and the port number): 

$ export EC2_HOME=/path/to/installed/ec2-commandline-tools
$ export PATH=$PATH:$EC2_HOME/bin
$ export EC2_PRIVATE_KEY=~/.euca/euca2-*-pk.pem
$ export EC2_CERT=~/.euca/euca2-*-cert.pem
$ export EC2_URL=http://your.cloud.server:8773/services/Eucalyptus

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: 

$ ec2-describe-availability-zones

In the output of the above command, you should see the cluster's front-end hostname displayed along with the status of 'UP' and a short description of how many 'small' instance types the cloud can execute (002/002 means 2 available out of 2 total). If the response is different or if the number of available instances is 000/000, then contact your cloud administrator about the problem.

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
KEYPAIR keyname ...
-----BEGIN RSA PRIVATE KEY-----
<key contents>
-----END RSA PRIVATE KEY-----

$ cat >mykey.private 
(paste the key contents, including BEGIN and END lines, printed out by the previous command)

$ 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)

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@one-of-the-ip-addresses

To terminate instances, use: 

$ ec2-terminate-instances <emi-id1> <emi-id2> ... <emi-idn>

Please, see Amazon's EC2 Getting Started Guide for more information about these command-line tools. Keep in mind that not all tools are currently supported.