Euca2ools

%define=code bgcolor=#BEE554 padding=3px indent lframe% %define=output bgcolor=#FFCCCC padding=3px indent lframe% [++Euca2ools User Guide++]


 * 1) Introduction to Euca2ools
 * 2) Installation
 * 3) Initial Setup
 * 4) Generating a Keypair
 * 5) Finding Available Images
 * 6) Creating an Instance
 * 7) SSH to VM
 * 8) Creating and Attaching Volumes
 * 9) Uploading Images
 * 10) Deleting Images
 * 11) References

[+Introduction to Euca2ools+]

Euca2ools is a package of command-line tools for interacting with the Eucalyptus cloud infrastructure.

Summary of Features
 * Query of availability zones (i.e. clusters in Eucalyptus)
 * SSH key management (add, list, delete)
 * VM management (start, list, stop, reboot, get console output)
 * Security group management
 * Volume and snapshot management (attach, list, detach, create, bundle, delete)
 * Image management (bundle, upload, register, list, deregister)
 * IP address management (allocate, associate, list, release)

Euca2ools will interact with a Eucalyptus cloud up to the point where you have a VM running and you have told it to allow SSH connections. After that, you will have to use SSH to control the VM. This guide will help you get to that point.

[+Installation+]

Euca2ools can only be installed in Linux. You can install from source code or by using a package manager. Below is a list of installation guides for several Linux distributions:


 * %newwin%[|Install from source]%%
 * %newwin%[|CentOS]%%
 * %newwin%[|OpenSUSE]%%
 * %newwin%[|Fedora]%%
 * %newwin%[|Debian]%%

For most of these you can just use a package manager utility to install it, for example: apt-get install. If you follow this method be careful and make sure to check you have the correct version installed. We recently found out that some that did it this way, have received old versions that may cause you to have errors running certain things.

To install the latest and greatest from source i suggest many also take a look at Dhimitris blog post on it. You can also download Euca2ools by cloning with git from https://github.com/eucalyptus/euca2ools.git

[+Initial Setup+]

After you have Euca2ools installed, you will need to download your credentials in order to be able to connect to our cluster (Matrix) or the Eucalyptus Community Cloud (ECC). Be sure that you are %newwin%[|registered and authorized] on whichever server you wish to use before proceeding.

First, download the credentials zip file:
 * Matrix: %newwin% https://matrix.worcester.edu:8443/ %%
 * ECC: %newwin% https://ecc.eucalyptus.com:8443/ %%

After logging into the Eucalyptus web interface, click on your username at the top of the page (typically admin@yourusername). This will present a dropdown menu, and then click on "Download new credentials". After the download has finished, follow these next steps to unzip the file and provide the appropriate permissions:

(Note: you need superuser permissions for chmod commands)

>>code<< @@mkdir ~/.euca@@<< @@mv /path-to/name-of-the-key-file.zip ~/.euca@@<< @@cd ~/.euca@@<< @@unzip name-of-the-key-file.zip@@<< @@chmod 0700 ~/.euca@@<< @@chmod 0600 ~/.euca/*@@<< @@. ~/.euca/eucarc@@<< >><<<<

Run this at the terminal for eucarc persistence (credit--Matt M.):

>>code<< @@echo "[ -r ~/.euca/eucarc ] && . ~/.euca/eucarc" >> ~/.bashrc@@<< >><<<< If you are going to use multiple clouds, do not do this.

You now will able to connect your machine to a Eucalyptus cloud.

For users attempting to connect to Matrix from home: you need to edit your @@eucarc@@ file. Open @@~/.euca/eucarc@@ in a text editor, and replace the IP addresses in lines 2-4 with @@matrix.worcester.edu@@. Leave everything else the same, including the port number. Save eucarc and re-run it (@@. ~/.euca/eucarc/@@). You will now be able to connect to the Matrix cloud from outside WSU.

[+Generating a Keypair+]

Here you will generate a keypair to be able to SSH into a VM instance. You will need to generate a keypair for every Eucalyptus cloud that you want to connect to.

>>code<< @@euca-add-keypair mykey | tee mykey.private@@<< @@chmod 0600 mykey.private@@<< >><<<< You should replace mykey with something more identifiable, like your name.

Again, make sure to run chmod as superuser. If it was successful, there will be an output of a large string of characters followed by @@-END RSA PRIVATE KEY-@@. Note that you can only do this once per keypair. If you try running the @@euca-add-keypair@@ again with a keypair you have already created, you will get this error:

>>output<< @@KeyPair:@@<< @@Creation failed. Keypair already exists: mykey@@<< >><<<<

If you need to recreate your keypair, delete your keypair as shown and then you will be able to generate a new keypair:

>>code<< @@euca-delete-keypair mykey@@<< >><<<< ''This will not delete the mykey.private file. But re-running the euca-add-keypair command will overwrite the existing file.''

To check your keypair(s) registered with Euca2ools:

>>code<< @@euca-describe-keypairs@@<< >><<<<

[+Finding Available Images+]

Now we are ready to find an image to create an instance on.

>>code<< @@euca-describe-images@@<< >><<<<

This will generate a list of available images. Look for one that has the words "public" and "machine", like so:

>>output<< @@IMAGE  emi-43811644    centos5.5-image-bucket2/root_nginx-201111231.manifest.xml@@<< @@paulwang       available       public          x86_64  machine  eki-6CBD12F2   e@@<< @@ri-A97113E4''@@<< >><<<<

Make note of the emi-id, in this example it is @@emi-438111644@@.

[+Creating an Instance+]

With the emi-id you have from the step above, you can now create an instance on that image.

>>code<< @@euca-run-instances -k mykey -n  @@<< >><<<<

This will by default create a virtual machine with 1 processor, 128 MB memory, and 2 GB storage. If you need a more powerful machine, you can add the parameter @@-t @@. The type can be one of five options: @@m1.small@@, @@c1.medium@@, @@m1.large@@, @@m1.xlarge@@, or @@c1.xlarge@@. If it was successful, you should get an appropriate message. If not, you should go back and pick a different image. Now you can view this instance (and any others you may have created):

>>code<< @@euca-describe-instances@@<< >><<<<

It may take a few minutes for your VM to become available, but when it is, you should see output like this:

>>output<< @@RESERVATION r-4950802 YourName default@@<< @@INSTANCE i-3A460675 emi-43811644 euca-123-456-789-012.eucalytpus.@@<< @@eucasys.com euca-987-654-321-098.eucalyptus,internal pending mykey 0 m@@<< @@1.small 2012-03-12T05:40:48.428Z open eki-6CBD12F2 eri-A97113E4@@<< >><<<<

Make note of your instance-id, bolded above.

[+SSH to Your VM+]

Now that your instance has been successfully created, you are ready to SSH in to remotely control it. These commands will allow your instance to be connected by SSH over the internet, and then connect to it.

This is how you can generate an accessible instance IP:

>>code<< @@euca-allocate-address@@<< >><<<<

Associate & authorize the allocated address with your VM instance:

>>code<< @@euca-associate-address  -i @@<< @@euca-authorize -P tcp -p 22 -s 0.0.0.0/0 default@@<< >><<<<

Make sure that port 22 has been authorized:

>>code<< @@euca-describe-groups@@<< >><<<<

SSH in to your instance:

>>code<< @@ssh -i /path/to/mykey.private root@@@<< >><<<<

If you can not SSH in yet try:

>>code<< @@euca-authorize -p 22 default@@<< >><<<<

If you are still having problems check your .ssh folder and delete(or modify) the known_hosts file.

[+Creating and Attaching Volumes+]

You have the ability to create dynamic volumes and attach them to your instance. The volumes are created in availability zones. To list availability zones, run the following command:

>>code<< @@euca-describe-availability-zones@@<< >><<<<

You should see something similar to this:

>>output<< @@AVAILABILITYZONE open xxx.xxx.xxx.xxx@@<< >><<<<

In this case your availability zone is @@open@@. You can now create a volume for your instance. This command will create a 1 GB volume:

>>code<< @@euca-create-volume -s 1 -z @@<< >><<<<

Now you can get the volume-id of the volume you just created:

>>code<< @@euca-describe-volumes@@ >><<<<

>>output<< @@VOLUME vol-76E10722 1 open available @@<< >><<<<

The volume-id in this example is @@vol-76E10722@@. Attach the volume to your instance using the following command:

>>code<< @@euca-attach-volume -i  -d /dev/sdb @@<< >><<<<

From this point on you can control the volume like any storage volume. For example, this will mount the volume and make it ready to use:

>>code<< @@sudo mkfs.ext4 /dev/sdb@@<< @@sudo mkdir /mnt/sdb@@<< @@sudo mount /dev/sdb /mnt/sdb@@<< >><<<<

NOTE: the above is run on the VM through SSH.

You can detach a volume that you have already attached to your instance:

>>code<< @@euca-detach-volume @@<< >><<<<

[+Terminating an Instance+]

If you are finished with your VM, you can terminate the instance to free up your allocated resources on the server.

>>code<< @@euca-terminate-instances @@<< >><<<<

[+Uploading Images+]

Images compatible with our Eucalyptus cloud are available to download on the main screen after you log in using the web interface. You must have admin credentials to upload and register images. After downloading the image archive, extract it somewhere. There will be 3 files you will be using: 1. the image file (ex. @@centos.5-3.x86.img@@); 2. the kernel (ex. @@vmlinuz-2.6.28-11-server@@); 3. ramdisk (ex. @@initrd.img-2.6.28-11-server@@).

Uploading images and kernels are exactly the same: first, you bundle the image; then, you upload the bundled image; once it is uploaded, finally you register it. An example is below: >>code<< @@euca-bundle-image -i --kernel true@@<< @@euca-upload-bundle -b -m /tmp/ .manifest.xml@@<< @@euca-register / .manifest.xml@@<< >><<<<

The kernel bucket can be any name you wish, such as @@my-kernel-bucket@@. Your kernel is now uploaded and registered. Make note of the @@eki-id@@ that is displayed in the output.

>>code<< @@euca-bundle-image -i --ramdisk true@@<< @@euca-upload-bundle -b -m /tmp/ .manifest.xml@@<< @@euca-register / .manifest.xml@@<< >><<<<

The ramdisk bucket can be any name you wish, such as @@my-ramdisk-bucket@@. Your ramdisk is now uploaded and registered. Make note of the @@eri-id@@ that is displayed in the output.

>>code<< @@euca-bundle-image -i --kernel --ramdisk @@<< @@euca-upload-bundle -b -m /tmp/ .manifest.xml@@<< @@euca-register / .img.manifest.xml@@<< >><<<<

The image bucket can be any name you wish, such as @@my-image-bucket@@. Your image is now uploaded and registered, and associated with your kernel and ramdisk. Make note of the @@emi-id@@ that is displayed in the output. You will use this to create an instance of your image in the above step, Creating an Instance.

Using these commands you will able to upload a kernel, a ramdisk, and an image of your choice and they will all be associated with each other. If you do not want your image associated with a particular kernel and ramdisk, leave the options @@--kernel @@ and @@--ramdisk @@ out of the @@euca-bundle-image@@ command. In this case, when running an instance, make sure to specify the kernel and ramdisk at that time:

>>code<< @@euca-run-instances -k mykey -n 1 --kernel  --ramdisk  @@<< >><<<<

[+Deleting Images+]

To delete a bundled image:

>>code<< @@euca-delete-bundle -b @@<< >><<<<

This will delete all images inside @@ @@. To delete a specific image in a bundle, specify its manifest using the @@-m @@ argument.

To delete a bundle after deleting all of its images:

>>code<< @@euca-delete-bundle -b  --clear@@<< >><<<< Only an empty bundle can be deleted.

[+References+]


 * 1) %newwin% http://open.eucalyptus.com/wiki/EucalyptusGettingStarted_v1.6 %%
 * 2) %newwin% https://wiki.smu.edu.sg/flyer/Main_Page %%
 * 3) %newwin% http://wiki.debian.org/euca2ools %%
 * 4) %newwin% http://open.eucalyptus.com/wiki/EucalyptusImageManagement_v1.5.2 %%
 * 5) %newwin% http://open.eucalyptus.com/book/export/html/4286 %%