Introduction

This page gives you the first keys to using Ubuntu Cloud Guest official images on Amazon EC2. Please follow the instructions below to use them.

Running Ubuntu Cloud Guest on Amazon Web Services requires you to go through the following steps:

Create your account on Amazon (if you do not already have one) and setup your credentials

Install Amazon EC2 API Tools

Instantiate your images(s)

Configure your instance

Types of credentials

First, a note on the area of EC2 that most often confuses people: credentials. There are multiple different kinds of credential, Amazon uses slightly non-standard nomenclature, and it's not always clear which credential is required for a given application.

Signon credentials: These are the email address/password pair that you use when you sign up. You use these to sign on to the AWS console, and can be considered the "master" credentials as they allow you to regenerate all other types of credentials.

Access Credentials: There are three types: access keys, X.509 certificates and key pairs. The first and second type allow you to connect to the Amazon APIs. Which type of credential depends on which API and tool you are using. Some APIs and tools support both options, whereas others support just one. The third type is SSH public/private key pairs that are used for initial logins to newly created instances.

access keys: Symmetric key encryption. These are for making requests to AWS product REST or Query APIs. Can be obtained/regenerated from the Access Keys tab on the AWS Security Credentials page.

X.509 certificates: Public key encryption. Use X.509 certificates to make secure SOAP protocol requests to AWS service APIs. These are the credentials you will use when using the command-line ec2 api tools. Can be obtained/regenerated from the X.509 Certificates tab on the AWS Security Credentials page.

key pairs: SSH key pairs. When you create an instance, Amazon inserts the public key of your SSH key pair into your new instance so that you can log in using your private key. You can add new SSH key pairs through the AWS management console by clicking on Key Pairs under Networking and Security in the Navigation pane and then the Create Key Pair button. After specifying a name you will be prompted to download and save your private key. EC2 stores the public portion of your key pair, and inserts it into /home/ubuntu/.ssh/authorized_keys when you instantiate your instance. If you lose this private key, it cannot be downloaded again; you will need to regenerate a new key pair.

Setting up an Amazon account

You can associate your new EC2 account with an existing Amazon account (if you already have one), or create a new account.

Go to http://aws.amazon.com, and select Sign-up Now. Sign in to your existing Amazon account or create a new one.

Click Key Pairs under Networking and Security in the Navigation pane and then click the Create Key Pair button (save it in e.g. ~/.ec2/ec2.pem). This private key is for making SSH connections to newly created instances.

Download the private key and the certificate (save them in e.g. ~/.ec2/cert-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem and ~/.ec2/pk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem).

Make your credential files private: chmod go-rwx ~/.ec2/*.pem

Scroll to the bottom of the page and note your account ID (a number of the form XXXX-XXXX-XXXX).

If at a later time you discover you need to generate a new X.509 certificate, click on "Your Account" at the top of the EC2 console page. You may need to click the small button with two down arrows near the top right of the EC2 console page to make the "Your Account" link visible. Then in the "Access Credentials" box, click the tab named "X.509 Certificates" and click "Create a New Certificate". Download the private key and certificate when prompted.

Official Ubuntu Cloud Guest Amazon Machine Images (AMIs)

The Official AMI Ids can be obtained from http://cloud-images.ubuntu.com/locator/ec2/. Official Ubuntu AMIs are published by the 'Canonical' user, with Amazon ID '099720109477'. Images containing the string 'ubuntu' but not owned by that ID are not official AMIs.

The EC2_KEYPAIR is the Key Pair Name as listed in the AWS Management Console under Networking and Security -> Key Pairs, not the filename of the private key file that you saved to your local machine. This variable tells ec2 which SSH public key to insert into the instance during instantiation.

Note: If this fails due to "Client.AuthFailure" then ensure you have signed up for both AWS and ec2 with amazon.com, and have provided valid payment details. Also double check that the EC2_PRIVATE_KEY and EC2_CERT point to the correct locations.

EC2 security groups

Security groups allow you to specify firewalling rules for your instances. These firewalling rules are independent of, and in addition to, the software firewalling provided by the instance's operating system (iptables in the case of modern Ubuntu systems). Security groups must be defined before you create the instances that you would like to be members of those security groups. You specify the security groups to add an instance to at creation time with the -g option to the ec2-run-instances command. You cannot add an existing instance to a security group.

How you set up your security groups is up to you. You may choose to set up security groups that correspond to server functions, or have a separate security group for each instance. An instance may be a member of multiple security groups. If you don't specify any security groups when you instantiate an instance, it will be added to the default security group. Our examples use the default security group, but keep in mind that this means that this causes an inability to set up firewalling rules in a granular fashion.

If you wish to create a more complex security group configuration, you can do so with these commands:

To see the status of your instance, you can run the following command:

ec2-describe-instances

In order to log in to your instance, you will need to authorize network access to the ssh port for the default security group:

ec2-authorize default -p 22

You may then log in to the instance using ssh:

ssh -i <private SSH key file> ubuntu@<external-host-name>

The <private SSH key file> is the filename of the private SSH key that corresponds to the Amazon Key Pair that you specified in the ec2-run-instances command. The <external-host-name> can be found using the ec2-describe-instances command. An example SSH command:

ssh -i ~/.ec2/ec2.pem ubuntu@ec2-135-28-52-91.compute-1.amazonaws.com

Once you have logged in, you may begin to set up and use the instance just like any other Ubuntu machine.

You will be billed as long the host is running1, so you will probably want to shut it down when you're done. Note that each partial instance-hour consumed will be billed as a full hour.