CS270 -- Eucalyptus CLI Tutorial for Class Project

this page last updated: Thu Jan 5 09:16:09 AM PST 2023

For the file system project, you will need to use the Eucalyptus cloud that the university has set up. This page will provide some guidance on how to use the cloud to implement your project.

Getting access to Eucalyptus

To get an account on the Eucalyptus cloud for CS270, you must email me with the following information I will send you and account ID and password once I have recorded your team information.

Eucalyptus (like Amazon AWS) has a notion of accounts and users. Multiple users can be part of a single account. When an account is created, it is created with a single user with the id admin. For the purposes of this project, it is fine for all team members to share the admin user id to the team's account.

Using the Eucalyptus Console

There are two ways to access Eucalyptus: via a web-based console or via the AWS command line tools. To use the console, point your browser to https://eucaconsole.aristotle.ucsb.edu. The account name is the account ID that I sent to you. The user name is admin, and the password is the password that I sent.

Please keep that password handy. The "forgot your password" button will not work because we have not attached the account to an email address. If there is a password mishap, email me and I can have it reset manually, but it might take some time as the cloud administrators are quite busy.

The Eucalyptus console is pretty self-explanatory and there are documents available on-line.

Using the Command Line Tools

You are free to use the console for this project. However if you would like to use the AWS command-line tools, the remainder of this tutorial will explain how you can.

Installing the AWS command-line tools

The AWS documentation on how to install the AWS CLI tools explains the installation procedure. There are several variants. I'll cover how to install the tools in your CSIL account (which is a Fedora Linux system).

First, download the zipped code from AWS using curl. 

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
When you unpack the code, it will create a subdirectory called "aws" in the current directory. To unpack, type 
unzip awscliv2.zip
Next, to do a local install, you will need to tell the installer where to put the aws executables and the CLI code and specifications. The executables directory (bin-dir) must be in your PATH. For my faculty account on CSIL, here are the commands I used. Change /cs/faculty/rich to your account's file system prefix (type pwd to see it for your local directory). 
mkdir -p /cs/faculty/rich/bin /cs/faculty/rich/aws-cli
./aws/install --bin-dir /cs/faculty/rich/bin --install-dir /cs/faculty/rich/aws-cli
export PATH=${PATH}:/cs/faculty/rich/bin
This command installed the executables in /cs/faculty/rich/bin and the code and other components in /cs/faculty/rich/aws-cli.

Configuring your Environment

By default, the AWS CLI tools work with AWS. To get them to work with Eucalyptus, you need to add a few variables and an alias to your shell environment. The easiest way to do this is to add lines to the .bashrc file in your home directory. This file is executed by the shell each time you log in so each shell session will be set up correctly to work with Eucalyptus. If, at some point, you want to use this same AWS CLI installation with AWS, you will want to comment out or remove the Eucalyptus environment variables.

Edit the file ~/.bashrc with your favorite text editor. Mine is "vi" so I would type 

vi ~/.bashrc
You will need to set three up environment variables using the bash export command. These variables set up your access key (which is like a user ID), your secret key (which is your password) and the default region to use for AWS CLI commands. To set these add the lines (replacing the full path to my bin directory to yours): 
export PATH=${PATH}:/cs/faculty/rich/bin
export AWS_ACCESS_KEY_ID=XXX
export AWS_SECRET_ACCESS_KEY=YYY
export AWS_DEFAULT_REGION=eucalyptus
to the end of your .bashrc file where XXX is your access key and YYY is your secret key. If you were to use this installation with AWS, you would need to change these lines to specify your AWS access key, secret key, and the AWS region you want to use as a default.

You also need to tell the AWS CLI tools what endpoint to use for contacting the cloud when the cloud is not AWS. You can specify a "--endpoint-url" argument to each command, but this is a little cumbersome. In this class, we will only be using the EC2 features, so a simple way to automate inclusion is to alias the aws command to include the endpoint. Add the following line to the end of your .bashrc file after the exports 

alias aws="aws --endpoint-url http://ec2.poc.aristotle.ucsb.edu:443 --no-paginate --no-verify-ssl"
and write out the file.

Because your secret key is in the .bashrc file, you want to change its permissions so that it is only readable by you. Run the command 

chmod 600 ~/.bashrc
to set the permissions to bet read and write for you only.

Now activate your latest changes and check to make sure that the CLI tools are working. Type 

aws --version
and you should see something like 
aws-cli/2.9.12 Python/3.9.11 Linux/6.0.15-200.fc36.x86_64 exe/x86_64.fedora.36 prompt/off
Next, configure the output format to be text. To do so, create a .aws directory in your home directory with the command 
mkdir -p ~/.aws
and create a config file 
vi ~/.aws/config
In this file, put the following content 
[default]
output = text
Next, source your ~/.bashrc to set your environment variables in the current session. 
source ~/.bashrc
Next, test to make sure that you are contacting the Eucalyptus cloud properly. Type 
aws ec2 describe-availability-zones
and you should see something that looks like 
AVAILABILITYZONES	eucalyptus	available	ucsb
AVAILABILITYZONES	eucalyptus	available	aristotle
AVAILABILITYZONES	eucalyptus	available	race

Eucalyptus Commands

There are a bunch of AWS commands which are all documented and many, but not all, of them will work on this Eucalyptus installation. When in doubt, just give it a try.

However, for this class, though, you'll only need to be able to

We'll go through these actions here. WARNING: Like AWS, Eucalyptus doesn't have many guard rails. In particular, it doesn't prompt the user for confirmation when a command could cause a potentially catastrophic (from your perspective) data deletion if that is what the command semantics say will happen. There are no backups for the Eucalyptus installation so if it is lost, it is lost. Be SURE that you are making your own backup copies of everything you cannot lose.

Launching an Instance

First, it is important to understand some of the cloud resource terminology that Eucalyptus uses. An instance is a VM running in Eucalyptus.

Using Instances

There are several steps that must be done when you first start using Eucalyptus before you run your first instance. They involve Once you have done these things once, all subsequent instance launches can use the same configuration.

First, though, it is important to understand some of the cloud resource terminology that Eucalyptus uses. An instance is a VM running in Eucalyptus. To launch an instance, you need to specify an image that contains the operating system software you'd like to have in the instance.

That is, when you launch an instance, the instance needs an OS (I will use CentOS 9) which comes from an image.

PLEASE READ THIS: Before moving on, it is important to understand that cloud instances are not persistent. That is, when you run an instance, anything you save in the instance will be lost when you shut the instance down.

Think of an instance as being like a Linux process, except that it has local disk storage. When you kill a process or when a process exits, all of the memory in the process is lost. If you haven't written that memory to disk, then it is gone and you can't get it back.

An instance is the same way except that it has a disk that is lost as well. When you launch and instance and you install your software, that software is written to a disk that is "ephemeral" which means it will be wiped clean by Eucalyptus when the instance shuts down and there is no way to recover the lost storage.

Thus, in this class, you will need to make sure that you do not keep anything you cannot lose in your instance. You can either put the source code in GitHub and push it when ever you have code that you can't lose (e.g. very often) or create a volume (see below) that will persist across instances.

However, instance storage is not persistent.. Please be sure you understand what this previous sentence means completely before moving on. If you are confused, contact me directly. It is vitally important that you not lose your work because you do not understand the cloud storage model.

With this understanding firmly in mind, the first step, then, is to query Eucalyptus for the images that are currently installed so that you can determine the identifier of the image that you will specify in the launch request for an instance. To see the installed images, type 

aws ec2 describe-images

The output from this command is lengthy. In particular, a few colleagues have asked to use the cloud while for their own purposes and they have installed images of their liking. To see the image you'll need for this class, try 

aws ec2 describe-images | grep "CentOS-Stream-9"

and you should see something like 

IMAGES	x86_64	2021-12-14T22:55:13.800Z	CentOS Stream 9 EBS - 2021-11-19	ami-b157b02b9b51c65ce	000494469007/CentOS-Stream-9.20211214.ebs	machine	CentOS-Stream-9.20211214.ebs	000494469007		True	/dev/sda	ebs	available	hvm

That's the image you'll need. Specifically, to launch an instance from this image, you'll need the image ID which begins with the prefix "ami-". way to get just this ID is

The image ID will not change unless we are forced, at some point, to reinstall Eucalyptus. Assuming that doesn't happen, you can use ami-b157b02b9b51c65ce for your CentOS 9 instances in this class.

Next, you will need to create an ssh keypair to use with your instance. When Eucalyptus launches your instance, it will automatically install an ssh key so that you can log into it once the instance is running. Access via ssh is the standard for Linux instances but you first need to create the ssh keys you'd like installed.

To create a keypair run 

aws ec2 create-key-pair --key-name mykeyname.key --query 'KeyMaterial' --output text > mykeyname.key

This command does two things. First, it generates an ssh key pair and sticks the private key in the file mykeyname.key. Second, it generates an internal name for the keypair and stores the public key inside Eucalyptus. When you launch an instance, you will specify the keyname and Eucalyptus will install the public key in the instance. You can then log in using the private key that has been stored in the file.

Note that ssh on Linux doesn't like private keys with open permissions. Thus, it is a good idea to immediately 

chmod 600 mykeyname.key

as soon as you create a key

Also, Eucalyptus isn't big on user and account names. If there is a problem, I won't be able to tell which account or user "owns" a particular instance. The convention, then, is to make "keyname" something descriptive since the keyname shows up in a listing of running instances. In this class, you should make your "keyname" be the name of your team. That way, I can contact you before doing something to an instance that requires some "service."

Configure the Cloud Networking

The AWS networking API requires that you create a default "virtual private cloud" or VPC which will determine things like what private IP addresses your instances will get. run the command 
aws ec2 create-default-vpc
and you will get the default configuration for Eucalyptus.

The other part of the networking initialization is to tell Eucalyptus what network ports should be opened for the instance once it is launched. Typically, you want to enable port 22 for TCP since that is the port used by ssh and ICMP ping so you can tell if your instance is "up." Do set up these firewall rules, type 

aws ec2 authorize-security-group-ingress --protocol tcp --port 22 --group-name default --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --protocol icmp --port -1 --group-name default --cidr 0.0.0.0/0

These commands tell Eucalyptus to allow TCP or ICMP traffic from anywhere (TCP on port 22 only) for ICMP to reach all instances launched in the security group default.

Launch an Instance

With this setup, the command to launch an instance is 

aws ec2 run-instances --key-name mykeyname.key --image-id ami-b157b02b9b51c65ce --instance-type t2.medium

This basic command will use the CentOS image and will inject the ssh key. Note that the key you use has to be the key you created. Eucalyptus will insert the public key for the private key that is in the file created by the create-key-pair command. It will also use the default security group so that the firewall rules you set up in the previous step will pertain to this instance.

Also note the instance type specifier. This tells Eucalyptus what size instance (in terms of cores, disk sizes, and memory) you would like to have in your VM. A "t2.medium" gives you 2 cores and 4GB of memory which should be enough for your file system project.

It takes a few moments (sometimes minutes) for Eucalyptus to get the instance running. After an instance launch, type 

aws ec2 describe-instances

from time to time. While the instance is starting up, the word pending will show up in the output of this command right next to keyname. Eventually, when the instance is ready, this field in the output will change to the word running. The output is prety verbose. You should see something like 

RESERVATIONS	000862777018	r-0eb5cbe4b0b60c19a
GROUPS	sg-1692cda276cefbc7f	default
INSTANCES	0	x86_64	c3c29356-b168-4acc-8bb5-ad043de08540 ami-b157b02b9b51c65ce	i-ca40123ea9a83dc7e	t2.medium	mykeyname.key	2023-01-06T17:23:58.962Z	ip-172-31-47-181.compute.internal	172.31.47.181	ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu	169.231.230.237	/dev/sda	ebs	True	NORMAL:  -- []	subnet-81bab7271c9aaa929	hvm	vpc-ded7f069f521288f9
BLOCKDEVICEMAPPINGS	/dev/sda
EBS	2023-01-06T17:23:59.098Z	True	attached	vol-7392618e848b7c4e8
MONITORING	disabled
NETWORKINTERFACES	Primary network interface	d0:0d:c5:c1:43:1c	eni-c5c1431c684fd1037	000862777018	ip-172-31-47-181.compute.internal	172.31.47.181	True	in-use	subnet-81bab7271c9aaa929	vpc-ded7f069f521288f9
ASSOCIATION	ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu	169.231.230.237
ATTACHMENT	2023-01-06T17:23:58.974Z	eni-attach-e4f03eb4a79a18c37	True	0	attached
GROUPS	sg-1692cda276cefbc7f	default
PRIVATEIPADDRESSES	True	ip-172-31-47-181.compute.internal	172.31.47.181
ASSOCIATION	ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu	169.231.230.237
PLACEMENT	ucsb
SECURITYGROUPS	sg-1692cda276cefbc7f	default
STATE	16	running
At that point, the instance is ready To log into it you will need the public IP address for the instance. All instances get an IP address which is accessible to networks outside of Eucalyptus, and a private IP address for internal use only. The public IP address is the second IP address listed which, for this example, is 169.231.230.237.

To DNS or not to DNS -- that is the question. This installation of Eucalyptus has DNS enabled which means that each instance gets a public DNS entry (which UCSB correctly advertises) and an internal private DNS entry. For reasons that will become clear later in this class when we discuss cloud computing, public DNS will resolve to the private IP address if the resolution takes place within an instance. This mode is called "split horizon" DNS and it is what AWS implements. However, it can make things quite confusing if you are trying to script things and your scripts (or worse your scripting language) don't (doesn't) handle DNS perfectly. Thus, to avoid these headaches, I use IP addresses exclusively when I work with clouds (Eucalyptus or otherwise). You are free to develop your own style -- just understand that DNS isn't everything you think it might be in this context.

In this example, the DNS name that should be accessible from outside of the cloud is ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu. On CSIL, if that had been your instance, you would have been able to ping it by typing 

ping ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu
to ensure that it is up.

To log into the instance type: 

ssh -i mykeyname.key cloud-user@public_ip

CentOS images do not allow root logins as a default. For this example, you would log in as 

ssh -i mykeyname.key cloud-user@169.231.230.237
Once you have logged in, type 
sudo -s root
and you will become root. If you wish to enable the root login (thereby skipping the sudo step) then you can by typing 
sudo cp ~cloud-user/.ssh/authorized_keys /root/.ssh/authorized_keys
You should then be able to log in as 
ssh -i mykeyname.key root@public_ip

Logging out of the instance doesn't stop the instance. That is, if you log out, and then come back later and run the ssh command, the instance should still be running. You can always check on the running status of your instance or get its public IP address by running 

aws ec2 describe-instances
.

Terminating an Instance

You are welcome to leave an instance running and to simply log out of it when you are not using it. However, power failures, hardware failures, and system administrator (i.e. your instructor) errors do occur with greater frequency in an academic environment than one might want. Make sure you work is saved in a safe place early and often. There are no backups for this system.

If you want to shut an instance down, you need to get the instance ID. Run 

aws ec2 describe-instances

and get the instance ID from the sixth field of the line that begins with the word INSTANCES (it will begin with "i-"). For example, 

aws ec2 describe-instances | grep INSTANCES | grep mykeyname.key
looks for an instance that was started with the key "mykeyname.key". It should generate something that looks like 
INSTANCES	0	x86_64	c3c29356-b168-4acc-8bb5-ad043de08540 ami-b157b02b9b51c65ce	i-ca40123ea9a83dc7e	t2.medium	mykeyname.key	2023-01-06T17:23:58.962Z	ip-172-31-47-181.compute.internal	172.31.47.181	ec2-169-231-230-237.compute.poc.aristotle.ucsb.edu	169.231.230.237	/dev/sda	ebs	True	NORMAL:  -- []	subnet-81bab7271c9aaa929	hvm	vpc-ded7f069f521288f9

shows the output when I run it. If I wanted to terminate this instance I'd type 

aws ec2 terminate-instances i-ca40123ea9a83dc7e

As mentioned before, all data in the instance itself will be lost (including the disk storage) if I were to run this command.

Creating Persistent Volumes

Eucalyptus does have a way to create virtual disks that persist across the instance lifecycle. These disks are called volumes and the facility for managing them is called EBS (Eucalyptus Block Store). EBS is generally compatible with the AWS Elastic Block Store if you want to get more documentation.

In this class, you will need to create an EBS volume to use for the disk storage in your file system. You can also create a volume to hold your code and this volume will persist if your instance is terminated for what ever reason. However, the machine inside Eucalyptus that is implementing EBS volumes might have a disk crash and there are no backups so it is best if you also keep your class code backed up elsewhere.

To create a volume, you need to specify the availability zone and the size in GB. For this class, you should create volumes no bigger than 30GB in order to prevent us from having disk shortage problems. The command for creating a 30GB volume in AZ 'race' is 

aws ec2 create-volume -z race -s 30

Like instances, it takes a while for Eucalyptus to create your virtual resource. To see the status of the create request type 

aws ec2 describe-volumes

While Eucalyptus is working on your request, the status will be reported as creating. After the volume has been created successfully, the volume will be reported as available. Volumes also get assigned unique identifiers that begin with the string "vol-". You get the ID back from the create call and it is the second field in 

euca-describe-volumes
.

Attaching a Volume

Once a volume is created and it is in the available state it can be attached to an instance so that the instance may access it. Volumes are not shared. That is, a volume may be attached to at most 1 instance at a time. When a volume is attached, its status shows up as in-use and Eucalyptus will deny additional attach requests for it until it is detached.

To attach a volume to an instance you need

Because of a bug in libvirt for KVM, the device name is ignored -- sort of (careful with this problem -- see below). However, you must specify it in the call and it is good to try and make it a sane device name. Eucalyptus is using KVM as a hypervisor in the CS270 cloud so device names begin "/dev/vd". The device "/dev/vda" is used by Eucalyptus when it creates the instance. Eucalyptus also initializes /dev/vdb (in this image), formats it as an ext3 file system, and mounts it as /mnt. You should choose a device name that uses a letter other than the letter "a" or the letter "b." For example, 

aws ec2 attach-volume --device /dev/vdb --instance-id i-ca40123ea9a83dc7e --volume-id vol-7c6f712dd4d568175

attached volume vol-7c6f712dd4d568175 to instance i-ca40123ea9a83dc7e as what Eucalyptus thinks is device /dev/vdb. The only real way to tell when device KVM used, however, is to log into the instance before the attach, and type 

ls /dev/vd*

Then do the attach, then repeat the 

ls
and see what device name showed up. In this version of KVM (but not previous versions) it appears that it used the letters in order. Thus, the first volume attached shows up as /dev/vdb and then next as /dev/vdd and so on but you definitely want to verify this conjecture before depending on it. Sorry. We have spoken to the folks at Red Hat about this problem numerous times. No luck.

Detaching a Volume

You can either detach a volume explicitly with the 
aws ec2 detach-volume
command or by terminating the instance (the volume will be detached automatically as part of the terminate). However, Eucalyptus does not send a signal to the instance indicating that a terminate or detach is taking place. Thus, if your file system is mounted, and the state has not been flushed to disk, the detach or a terminate can leave the disk in a corrupt condition. Before detaching or terminating, then, it is best to log in, become root, and run the Linux 
sync
command to allow the instance to flush disk state. Then go ahead with the detach or terminate.

Image Conditioning

Once the image is running, you may want to add software packages to it that aren't included in the base CentOS 9 image. CentOS and RHEL both use the Red Hat package manager system called rpm which has a couple of convenient user front ends called dnf and yum. Using the yum utility, you can install additional software as long as it is either part of the standard CentOS repositories or it is located in some repository and you've taught dnf or yum where to find it. I'll cover the standard stuff here and let you read the documentation and commentary on how to use dnf and yum if you need something beyond what is in the standard repos. You have root within your instance so it is entirely at your disposal. You may install what ever you like as long as it is For example, I'm a C programmer so I require gcc, make, and gdb. I also use git I like having the man pages installed. Finally, I am using fuse3 as you will be for this class project. The base CentOS 6.4 image doesn't have these packages installed by default. To install them type 

dnf -y update
dnf -y install fuse3-devel
dnf -y install fuse3-libs
dnf -y install fuse3
dnf -y install gcc make automake autoconf

when logged in as root. The update will get the latest packages (it will take a while). If you plan to use Python, or Java, or some other technology, you may need to install them as well. The yum utility should take care of any package dependencies as long as what you want is available as part of the CentOS 9 Stream distro. If you go off the reservation, however, you will need to make your own way.

If you just use the image as it is provided, you will be using a version of CentOS 9 Stream which is supposed to be kept up to date. However, beware up updating too frequently as the packages in Stream change without the Q/A you might expect.