Corporate Home Open Source Home
Syndicate content
Eucalyptus

Table of Contents

Eucalyptus Administrator's Guide (1.1)

This is a binary-only beta release that relies on the Rocks cluster management platform for deploying Eucalyptus on a cluster. (We are additionally offering a source code tar-ball for those interested in Eucalyptus internals, but unfortunately our resources may not allow us to offer adequate support for those trying to install Eucalyptus from source.)

If you are familiar with Rocks and you don't care for superfluous explanations, you may want to start with the Quick Start page instead of this Guide.

Table of contents

  1. Prerequisites
  2. Installation
  3. Configuration
  4. User Management
  5. Image Management

1. Prerequisites

Eucalyptus 1.1 binary install minimally requires a Rocks V front-end system that has been configured to include the xen and java Rocks rolls. It is not necessary to have any compute nodes configured, but if compute nodes are configured they can be re-targeted as Eucalyptus nodes.

  • Follow the instructions in Rocks User's Guide to install it on your cluster. (Keep in mind that managing cluster nodes using Rocks requires full re-installation of software on them.)
  • Xen 3.0.2 is the only virtual machine platform currently supported. In Rocks, make sure the xen roll, which is a standard component of Rocks V installation, is included on the compute nodes.
  • Java 5 (or greater) is needed by the Eucalyptus components running on the front end. Including the java roll, which is a standard component of Rocks V installation, should accomplish that.
  • Eucalyptus requires the unlimited-strength policy files for JCE for the Java Virtual Machine. The current installer installs them automatically. Thus, if you are in a country where this is illegal, DO NOT install Eucalyptus. If you are unsure of your country's cryptography import restrictions, Sun's documentation may be able to answer that question: see "Other Downloads" at the bottom of
  • You must be root to install and run Eucalyptus. This document assumes that all commands will be executed as root.

If you have installed the previous version of Eucalyptus (or if you are re-installing the same version because the original installation failed), make sure that all previously started Eucalyptus-related processes are no longer running. Just to be safe, after shutting down Eucalyptus properly (via /etc/init.d/eucalyptus stop), kill potential errant processes with pkill -9 -f euca.

2. Installation

2.1 Download Eucalyptus roll

Download Eucalyptus rolls from our repository. We have both 32-bit and 64-bit versions. Place that Eucalyptus Rocks ISO image on the front end. Once again, this ISO image is not very useful without a Rocks installation with xen and java rolls. Burning it onto a CD is not necessary.

2.2 Add Eucalyptus to Rocks

Install the Eucalyptus Roll and enable it for deployment on the cluster boot nodes. 

$ rocks add roll clean=1 /path/to/eucalyptus-5.0-1.*.disk1.iso

(Caution: don't use a ../ path on this command line!) 

$ rocks enable roll eucalyptus
$ cd /home/install && rocks-dist dist
$ rocks list roll

The output of the last command should include a line indicating that the eucalyptus roll is installed and enabled. It should also list "java" and "xen" rolls.

2.3 Install Eucalyptus on nodes

With the rocks roll now installed and enabled on the front-end, we can now start booting or rebooting nodes and instructing the system to rebuild them with eucalyptus installed and running, using standard "rocks" tools.

  • OPTION 1: If you don't have all the compute nodes that you would like to use with Eucalyptus, run the following command on the front-end to add more of them: 
 $ insert-ethers

At the prompt, select 'VM Container' and wait for the next screen. At this point, the front-end is waiting for nodes to boot. Boot your nodes, and wait for their MAC addresses to appear in the insert-ethers window.

  • OPTION 2: If you have all the nodes that you want to use with Eucalyptus already registered in your system, perform the following command to re-target them for use with Eucalyptus: 
 $ rocks set host pxeboot vm-container-0-0 action=install
 $ rocks set host pxeboot vm-container-0-1 action=install
 #... (repeat this for each node you want to use with Eucalyptus)

When done, reboot your nodes (e.g., by logging in with ssh into them and running "reboot"). 

  $ ssh vc0-0 reboot
  $ ssh vc0-1 reboot
  #... (repeat this for each node you want to use with Eucalyptus)

With either option, the Eucalyptus Roll is being installed on your nodes as they boot. When the installation process is complete, your nodes will reboot (for the second time). At this point, the nodes are fully configured with the Eucalyptus node controller software running.

2.4 Install Eucalyptus on the front-end

As soon as all nodes have rebooted for the first time, you may proceed with front-end software installation on the Rocks front end (otherwise, you'll have to add the nodes "manually" later): 

$ kroll eucalyptus > build.sh
$ sh ./build.sh

If you get problems with ssh and rsync connecting to compute nodes, then you ran the command too early. That is OK, but you will have to propagate the keys to those nodes manually: 

$ /opt/eucalyptus-1.1/usr/sbin/euca_sync_key

If this command also prints out connection errors, the nodes have not all rebooted, yet. Try again in a bit. (Incidentally, if you want to add more nodes into the Eucalyptus cloud later, you would have to add their host names to the NODES= in /etc/default/eucalyptus and re-run euca_sync_key.)

When this is complete (or when you have enough nodes that are working), the Eucalyptus system is fully installed and is ready to use once some first-time administrative tasks are complete.

2.5 Finalizing Eucalyptus Installation

To finalize the installation of Eucalyptus the administrator must login as admin and configure the system and (optionally) register an image.

2.5.1 Login as admin

Go to the following location (note the https prefix):

https://your.front.end.hostname:8443/

Your browser will flag the Web site as one using an untrusted (self-signed) certificate. Accept it.

You will be presented with a login screen, at which point you can log in using the username admin and password admin. The first time you log in, the system will require you to change your password and enter a valid administrator email address. This address will be used whenever a new user requests an account on your Eucalyptus system.

2.5.2 Registering the test image (optional)

Please see the section Image Management.

2.6 Installation Complete

Now that you've finished the installation, the system is ready for users to sign up and start using your cloud. See the section on User Signup below for more information about that.

As administrator, you may interact with the system in precisely the same manner as your users, with the exception that your keys will allow you to inspect and terminate all instances running on the system, regardless of which user owns them. Next, you would probably want to generate keys and try using the system.

3. Configuration

3.1 Adding/Removing Nodes

Once you have a running Eucalyptus system you can add/remove vm-containers by editing /etc/default/eucalyptus and adding/removing your vm-container's hostname to/from the list of NODES: 

# The list of Node Controllers the cluster controller will be in charge
# of. For example on the rocks cluster you can run rocks list host to
# find out the list of machines available to you (in our case we are
# interested in the VM Container kind).
NODES=" vm-container-0-0 vm-container-0-1"

Whenever you add new nodes into the system, propagate cryptographic keys to them as follows: 

$ /opt/eucalyptus-1.1/usr/sbin/euca_sync_key

4. User Management

4.1 User sign-up

Users interested in joining the cloud should be directed to the front-end Web page (note the https prefix):

https://your.front.end.hostname:8443/

As soon as the administrator logs in for the first time and enters the email address to be used for application requests, thus activating the Web site for use by others, the login box of the Web site will have an "Apply for account" link underneath it. After a user fills out the application form, an email is sent to the administrator, containing two URLs, one for accepting and one for rejecting the user.

Note that there is no authentication performed on the people who fill out the form. It is up to the administrator to perform this authentication! The only "guarantee" the administrator has is that the account will not be active unless the person who requested the account (and, hence, knows the password) can read email at the submitted address. Therefore, if the administrator is willing to give the account to the person behind the email address, it is safe to approve the account. Otherwise, the administrator may use the additional information submitted (such as the telephone number, project PI, etc.) to make the decision.

Accepting or rejecting a signup request causes an email message to be sent to the user who made the request. In the case of an acceptance notification, the user will see a link for activating the account. Before activating the account, the user will have to log in with the username and password that they chose at signup.

5. Image Management

In order to use Eucalyptus, Xen images must be registered with the system. We have provided a small, simple version of linux that you can use to test. This section walks through the steps of registering the euca-ttylinux image with Eucalyptus.

5.1 Download the image

Download the image and place it on the front-end: 

$ cd
$ wget http://eucalyptus.cs.ucsb.edu/releases/euca-ttylinux.tgz

Untar the image, and cd to the directory 'ttylinux'. 

$ tar zxvf euca-ttylinux.tgz
ttylinux/
ttylinux/vmlinuz-2.6.16.33-xen
ttylinux/ttylinux.img
$ cd ttylinux

The two files are the Linux kernel and the root file system image, respectively. The default root password for the image is root. If you want to change or disable it, you need to modify the password file inside the root file system (by mounting it and editing the files).

5.2 Register the Image

Provided with the Eucalyptus installation is the tool euca which is used to register images. To register an image you need to know the following information:

  • Filesystem Image: used as the root filesystem.
  • Kernel Image: kernel used to boot the system.
  • Ramdisk Image: ramdisk supplied to the kernel at boot time. (optional)

Here is how to invoke euca to register the test image with Eucalyptus: 

$ /opt/eucalyptus-1.1/usr/sbin/euca add_image \
  --disk-image ttylinux.img \
  --kernel-image vmlinuz-2.6.16.33-xen \
  --image-name ttylinux
# replace ttylinux.img with your disk image
# replace vmlinuz-2.6.16.33-xen with your kernel image
# replace ttylinux with the name of your choosing

This makes a copy of the image, so the files in ttylinux directory may now be deleted.

At this point, you may add addition Xen images that you may have. The 'euca' command supports installation of a ramdisk if your image requires one (see the 'euca --man' output for more information).

Navigation
User login