First steps as a Eucalyptus user

This document briefly introduces common commands used as a Eucalyptus user. It is a very basic guide.

Prerequisite

• access to a Eucalyptus installation (which needs to be already tested and functioning)
• access to a machine with euca2ools (already tested and functioning)
• user credentials for such a Eucalyptus installation, assuming you've already unpacked them and have already sourced eucarc ( doing . eucarc within the directory where the aforementioned credentials were unpacked).

EMI and instances
EMI are images of full Linux distributions which the user can start and stop at will. Once an EMI has been started we will call it an "instance." The user will have root (administrator) access to it and most likely she will have to modify it to fit her needs (for example installing Apache or a database). WARNING: once the instance is terminated, all the changes made to that instance will be lost (data, packages installed etc..). If you have important work or data on it, you will have to move your content away from this instance before terminating (or use Walrus or EBS).

First, you should confirm that the CLC is accessible (front-end machine for Eucalyptus). Try
euca-describe-availability-zones
which should return something similar to
AVAILABILITYZONE wind 192.168.7.17
of course names and IPs will be different.

You can see which images are uploaded by running the following command:
euca-describe-images
For example, you may see
IMAGE eki-5ECD1670 kernel-centos-5.3-64/vmlinuz-2.6.28-11-generic.manifest.xml admin available public x86_64 kernel
IMAGE eri-A657175D initrd-centos-5.3-64/initrd.img-2.6.28-11-generic.manifest.xml admin available public x86_64 ramdisk
IMAGE emi-4A2C1226 centos-5.3-64/centos.5-3.x86-64.img.manifest.xml admin available public x86_64 machine

Note that the kernel starts with eki, ramdisk ss with eri and images start with emi. Note the image ID: you will have to use it to start an instance.

keypairs
To ssh into an instance, you will need to create a keypair (that is, a public/private keypair) where the public key will be uploaded into Eucalyptus (and ultimately into your instance) and the private keys remains with you. If you loose the private key you won't be able to ssh into running instances -- you will have to re-create a keypair and restart the instances. To view the keypair you already have created you can
euca-describe-keypairs
and to create a keypair you can
euca-add-keypair pippo > pippo.priv
With the above command you create a keypair called pippo (you can check it with describe command) and you save the private key into pippo.priv. Now change the permission on the private key so only you can see it
chmod 600 pippo.priv
and save the file for future use. If you want to delete an unused keypair you can use euca-delete-keypair,

security groups
Instances belonging to a user will be part of a private network, unless configured differently by the Eucalyptus administrator. This means their traffic is private (not seen by other instances). It is essential to define the type of access you want for your private network. This mechanism is called security groups and functions as a firewall for your instances. At the beginning users have 1 security group called default but additional groups can be created. For the following example you will need to give ssh access to the instances in the default group. To do so
euca-authorize -P tcp -p 22 -s 0.0.0.0/0 default
and you can check the status of a group with
euca-describe-groups
To create your own security group you can use euca-add-group.

starting and stopping instances
We can now start the instance with
euca-run-instance -k pippo -g default emi-4A2C1226This command will an instance of the selected image belonging to the security group default, using the keypair pippo which we created earlier. To check the status of the instance you can
euca-describe-instances
and you will see something similar to this
RESERVATION r-31A3055A admin default
INSTANCE i-36600627 emi-F88C157A 192.168.7.23 10.17.0.130 running mykey 0 m1.large 2010-02-03T20:30:09.184Z wind eki-5ECD1670 eri-A657175D
where all values will be different. Notice now that there are 2 IP addresses (they could be the same depending on how the administrator configured Eucalyptus), the status (in this case running but can be pending, terminated, or others) plus other information which may be useful (the keypair used, the type of instance -- large in this case -- the kernel and ramdisk used etc...).

The first IP is public whereas the second is private. The private IP is used to communicate between instances in the same security group and these instances won't have any firewall between them. The public IP connects to the instance and is subjected to the security group rules, which is why you must run the euca-authorize command shown above to allow ssh connection to the instance otherwise you won't be able to connect to it.

Once the instance is in running mode, you may try to
ssh -i pippo.priv root@192.168.17.23
where you must use your public IP as returned by euca-describe-instances.
If it doesn't work right away, give it few seconds: sometimes the instance takes a bit to acquire the IP address and to fully boot.

You can check the console output with euca-get-console-output and terminate the instance by either logging into it as root and running halt or by using euca-terminate-instances.

Using EBS
To have persistent data you can use EBS. You can create a volume with
euca-create-volume -s 1 -z wind the -s denotes size whereas -z is the cluster name (you can check the name of the clusters available to you with euca-describe-availability-zones). You may check the status of the creation by euca-describe-volumes and when the volume is available you can attach it to a running instance with euca-attach-volume -i i-3D2B07C8 -d /dev/sdd vol-502705C5 You must specify your particular instance ID and volume ID.. Note: not all hypervisors allow you to mount the volume as the specified disk so it may show up instead as the next available one.

Once the volume is attached it should show up on the scsi bus of the instance. You can now partition and initialize it as if it were a new hard disk. You may then save data on it. You can move the volume, using euca-detach-volume to detach from the current instance and attaching it to a new one.