Installing Eucalyptus from source
---------------------------------

Eucalyptus cloud setup consists of three components: the cloud controller
[ClC], the cluster controller(s) [CCs], and node controller(s) [NCs].
Typically, a ClC and a CC will run on the head node of a cluster, while an
NC will run on each of the compute nodes.  It is possible, however, to run
all components on a single machine. To have a fully functional Eucalyptus
installation you'll need at least one of each component.  

Note that some of the commands below require root privileges.  Please,
check section 2.d below for the list of software that Eucalyptus requires.

For the most up-to-date instructions, please visit the Eucalyptus web page
(http://eucalyptus.cs.ucsb.edu).


1. Download Eucalyptus
----------------------

From the Eucalyptus Web site:

  http://eucalyptus.cs.ucsb.edu/

you need to download 

- eucalyptus-<version>-src.tar.gz (Eucalyptus source)
- eucalyptus-<version>-src-deps.tar.gz (Eucalyptus dependencies)
- euca-ttylinux.tgz (a test VM image)

Unpack the Eucalyptus source:

; tar zvxf eucalyptus-<version>-src.tar.gz

Now you should have a directory eucalyptus-<version>. To simplify the
remainder of the installation, define EUCALYPTUS_SRC environment
variable to be the top of the source tree of eucalyptus and the 
variable EUCALYPTUS to be the directory where eucalyptus will be 
installed:

; cd eucalyptus-<version>
; export EUCALYPTUS_SRC=`pwd`
; export EUCALYPTUS=/opt/eucalyptus


2. Dependencies
---------------

Unpack the dependencies and create the directory you'll use to install
them:

; cd $EUCALYPTUS_SRC
; tar zvxf ../eucalyptus-<version>-src-deps.tar.gz 
; mkdir -p $EUCALYPTUS/packages/

Install the dependencies as follows:

a. Axis2

; cd $EUCALYPTUS/packages
; tar zxvf $EUCALYPTUS_SRC/eucalyptus-src-deps/axis2-1.4.tgz


b. Axis2/C

; export AXIS2C_HOME=$EUCALYPTUS/packages/axis2c-1.5.0
; cd $EUCALYPTUS_SRC/eucalyptus-src-deps/
; tar zvxf axis2c-src-1.5.0.tar.gz
; cd axis2c-src-1.5.0
; CFLAGS="-w" ./configure --prefix=${AXIS2C_HOME} --with-apache2=/usr/include/apache2 --with-apr=/usr/include/apr-1.0
; make ; make install


c. Rampart/C

; export AXIS2C_HOME=$EUCALYPTUS/packages/axis2c-1.5.0
; export LD_LIBRARY_PATH=${AXIS2C_HOME}/lib:$LD_LIBRARY_PATH
; cd $EUCALYPTUS_SRC/eucalyptus-src-deps/
; tar zvxf rampartc-src-1.2.0.tar.gz
; cd rampartc-src-1.2.0
; ./configure --prefix=${AXIS2C_HOME} --enable-static=no --with-axis2=${AXIS2C_HOME}/include/axis2-1.5.0
; make ; make install

Now edit the file $AXIS2C_HOME/axis2.xml: search for "Security" and change

  <!--phase name="Security"/-->

to

  <phase name="Security"/>

and save the file.


d. Other software

Additionally, the following dependencies need to be met:

- Java Development Kit (JDK), version 1.6 or above
- Apache ant, version 1.6 or above
- apache2 (httpd) developement files
- libvirt version 0.6.0 or higher development files and libvirtd
  configured and running properly
- GNU C compiler
- Make
- iptables
- vconfig
- bridge-utils

NOTE: The Eucalyptus dependencies may, in turn, depend on libraries or
packages not present in your installation: Please, refer to the 
documentation of the dependent package for help.

Furthermore, you are required to have functioning EC2 command-line
tools from Amazon.  The latest version of these tools that we support
are 'ec2-api-tools-1.3-30349' and 'ec2-ami-tools-1.3-26357' (See Amazon's
site for download and installation instructions.)

3. Building Eucalyptus
----------------------

; cd $EUCALYPTUS_SRC
; ./configure --with-axis2=$EUCALYPTUS/packages/axis2-1.4 --with-axis2c=$EUCALYPTUS/packages/axis2c-1.5.0 --enable-debug --prefix=$EUCALYPTUS
; cd clc/; make deps; cd ..
; make ; make install


4. Setting Up Eucalyptus
------------------------

To configure Eucalyptus you need to specify where Eucalyptus is
installed.  Moreover, for security reasons you need to specify the
Unix user that Eucalyptus's services will run as.  We suggest using
'eucalyptus' as such user.

These and other configuration options are stored in the file called
`$EUCALYPTUS/etc/eucalyptus/eucalytpus.conf` on all nodes.  You may
edit it manually or you may use the `euca_conf` script that we
provide. For instance, the minimal required configuration that should
be the same on all nodes can be recorded as follows:

; $EUCALYPTUS/usr/sbin/euca_conf -d $EUCALYPTUS -user eucalyptus $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf

At this point, if you plan to use Eucalyptus on more than one node,
you're ready to push the software out to the other nodes.  If you
installed Eucalyptus in its own directory, you can just sync the
entire package to all of the hosts listed above using whatever
mechanism you typically use to push changes to nodes (rsync, for
instance)

; rsync -a $EUCALYPTUS/ hostname1:$EUCALYPTUS/
; rsync -a $EUCALYPTUS/ hostname2:$EUCALYPTUS/
...

This would also be a good time to ensure that all of your nodes have
the Unix user for running Eucalyptus (e.g., `eucalytus` is in 
`/etc/passwd` on all nodes).

a. First-time Configuration

In following instructions we assume that CLC and CC are co-located on
a machine that we will refer to as the 'front end' and that NCs run on
'compute nodes'.  The instructions will also work if one physical
machine fulfills the role of both the front end and a compute node.

=== Front-end Configuration ===

Specify that the CLC and the CC are started on the front end:

; $EUCALYPTUS/usr/sbin/euca_conf -cc Y -cloud Y $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf

Next, add a list of hostnames on which you plan to run node controllers:

; $EUCALYPTUS/usr/sbin/euca_conf -nodes "<hostname1> ... <hostnamen>" $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf

Eucalyptus provides some options when it comes to configuring your VM
virtual network. By default, we enable the simplest but least
feature-ful networking mode, called SYSTEM in the eucalyptus.conf
file: Eucalyptus will assume that you already have a DHCP server
configured to serve IP addresses to VMs that start on cluster
nodes. Please consult the the brief explanation in the comments of the
configuration file and the Eucalyptus Networking document if you wish
to try other modes that will enable more features (security groups,
elastic IPs, etc.).

=== Compute-node Configuration ===

On each compute node, create a local directory where VM images are
placed temporarily when VMs are running (images will be cached under
the same path, too).  Instruct the nodes to run the node controller,
choose what hypervisor to use ('xen' or 'kvm'), and specify the path
for VM images. This path is used to store temporary VM images and it's
important it's empty (everything in it will be removed!).

; for x in hostname1 hostname2 ... hostnameN ; do \
 	ssh $x "mkdir -p /usr/local/instances/; $EUCALYPTUS/usr/sbin/euca_conf -nc Y -hypervisor kvm -instances /usr/local/instances $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf"
; done

Make sure that the user you have decided to run eucalyptus as
(username='eucalyptus' in the above example) has the ability to
control VMs through the node controller machine's libvirt
installation.  A good test is to run the command 'virsh list' as the
eucalyptus user to see if that user has the appropriate rights.

Finally, ensure that the networking settings in 'eucalyptus.conf' on
each of your nodes is configured properly (VNET_MODE and related
options, VNET_INTERFACE, VNET_BRIDGE.  See website for detailed
documentation on Eucalyptus Networking Modes).


5. Running Eucalyptus 
------------------------

To start eucalyptus run

; $EUCALYPTUS/etc/init.d/eucalyptus start

on each of your systems running eucalyptus.  To stop it, you would run

; $EUCALYPTUS/etc/init.d/eucalyptus stop

If you want to have eucalyptus started automatically when the machines is
(re)booted, you can add the following symlink

; ln -sf $EUCALYPTUS/etc/init.d/eucalyptus /etc/init.d/eucalyptus

and add the symlink to the distribution's booting process. For example if
you have update-rc.d available you can

; update-rc.d eucalyptus defaults

or if you have chkconfig available you can

; chkconfig eucalyptus on


6. First-time runtime configuration
-----------------------------------

To configure eucalyptus, after you started all components, you should
login to

  https://localhost:8443

where you should substitute localhost with the name of the host running the
cloud controller. (WARNING: on some machines it may take few minutes after
the starting of the Cloud Controller for the URL to be responsive the first
time you run Eucalyptus.) You will be prompted for a user/password which
are set to admin/admin.  Upon logging in you will be guided through three
first-time tasks:

1. You will be forced to change the admin password.
2. You will be asked to set the admin's email address.
3. You will be asked to confirm the URL of the Walrus service
   (the storage component of Eucalyptus) which should start 
   with the hostname or IP address of the cluster head node 
   where you are installing the ClC.

After completing the first-time tasks, you will see the 'Configuration'
tab.  At the very least, to enable Eucalyptus, you will need to add a
cluster by clicking the 'Add Cluster' button.  For a single-cluster
installation, the hostname is likely to be the one of the head node.  Be
sure to click 'Save clusters' before continuing.  This generates 
cryptographic keys that you will need to manually propagate to all
nodes (see instructions below).

Click the 'Credentials' tab and download your certificates via the
'Download certificates' button.  You will be able to use these x509
certificates with Amazon EC2 tools and third-party tools like
rightscale.com.

Create a directory, for example $HOME/.eucalyptus,

; mkdir $HOME/.eucalyptus

unpack the credentials into it, and source 'eucarc':

; . $HOME/.eucalyptus/eucarc

Note that you will have to source this file every time you intend
to use the EC2 command-line tools.

To finish the first-time configuration, propagate the cryptographic keys to
all nodes:

; $EUCALYPTUS/usr/sbin/euca_sync_key -c $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf 

This command uses rsync and ssh for key propagation, so you may be
prompted for the password of each of your cluster nodes.


7. Adding images to Eucalyptus
------------------------------

First off, be sure to source the 'eucarc' file before running the commands
below.  

To run VMs, one must add a root disk image, a kernel, and, optionally,
a ramdisk for the kernel.  Each is added to Walrus separately, using
three EC2 commands.  The following example uses the test image that we
provide.  Note that this image may or may not work within your local
hypervisor environment.  It is highly recommended that you try to
manually run the image on your hypervisor before trying to use it
within Eucalyptus.  Unpack it to any directory:

; tar zxvf euca-ttylinux.tgz

Add the root filesystem image to Walrus:

; ec2-bundle-image -i ttylinux.img 
; ec2-upload-bundle -b image-bukkit -m /tmp/ttylinux.img.manifest.xml
; ec2-register image-bukkit/ttylinux.img.manifest.xml

then the kernel

; ec2-bundle-image -i vmlinuz-2.6.16.33-xen --kernel true
; ec2-upload-bundle -b kernel-bukkit -m /tmp/vmlinuz-2.6.16.33-xen.manifest.xml
; ec2-register kernel-bukkit/vmlinuz-2.6.16.33-xen.manifest.xml

Although our test image does not require a ramdisk, one can be added 
in the manner similar to the kernel by using "--ramdisk true" flag.

Once you have registered at least one kernel and one ramdisk, you can go
back to the administrative interface (https://<cloudmanager>:8443), on the
'Configuration' tab and add the eki-xxxxxxxx and eri-xxxxxxxx as the
defaults kernel/ramdisk to be used when no kernel is specified.

Now you should be able to run all the EC2 commands.

---
Please see http://eucalyptus.cs.ucsb.edu for more info, downloads,
mailing lists and discussion forums.
