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:

  1. Create your account on Amazon (if you do not already have one) and setup your credentials
  2. Install Amazon EC2 API Tools
  3. Instantiate your images(s)
  4. 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.

  1. 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.

  2. 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.

    1. 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.

    2. 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.

    3. 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.

  1. Go to, and select Sign-up Now. Sign in to your existing Amazon account or create a new one.

  2. Go to, and select "Sign Up for Amazon EC2".

    1. Enter your credit card information.
    2. Complete your signup for the Amazon EC2 service.
  3. After signing up, you should end up at the EC2 console

    1. Create a key pair and download the private key
      1. 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.
    2. You will also need to set up your Amazon API credentials. Go to Account->Security Credentials

      1. click X.509 Certificates tab
      2. Create a new Certificate
      3. Download the private key and the certificate (save them in e.g. ~/.ec2/cert-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem and ~/.ec2/pk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem).
      4. Make your credential files private: chmod go-rwx ~/.ec2/*.pem
      5. 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 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.

Release images can be found at, for example 14.04 LTS Trusty Tahr can be found under

Installing the API tools

The EC2 API tools is now available for 9.04 users to install and configure the software. For previous versions of Ubuntu please see here.

  1. Make sure you have multiverse enabled and run the following command:

    sudo apt-get install ec2-api-tools

    If you're not on the latest ubuntu release the packages may be a bit old. You can make use of the awstools ppa by doing:

    sudo apt-add-repository ppa:awstools-dev/awstools
    sudo apt-get update
    sudo apt-get install ec2-api-tools
  2. Make sure you have the following environment variables set up in your shell profile. This is accomplished by adding the following lines to your ~/.bashrc if you use bash as your shell:

    export EC2_KEYPAIR=<your keypair name> # name only, not the file name
    export EC2_URL=https://ec2.<your ec2 region>
    export EC2_PRIVATE_KEY=$HOME/<where your private key is>/pk-XXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem
    export EC2_CERT=$HOME/<where your certificate is>/cert-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pem
    export JAVA_HOME=/usr/lib/jvm/java-6-openjdk/
    1. See Common Options for API Tools for a description of what these environment variables do.

    2. 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.

    3. The ec2 regions at the time of writing were:



US-East (Northern Virginia)

US-West (Northern California)

EU (Ireland)

Asia Pacific (Singapore)

Asia Pacific (Sydney)

Asia Pacific (Tokyo)

  1. Load the changes into the current shell environment:
    source ~/.bashrc
  2. Check to see if it's working by running the following command:
    ec2-describe-images -o self -o amazon

    Note: If this fails due to "Client.AuthFailure" then ensure you have signed up for both AWS and ec2 with, 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:

  •  ec2-add-group <group name> -d <description>
     ec2-delete-group <group name>
     ec2-describe-group [<group name> ...]

See the Using Security Groups section of the User Guide for Amazon EC2 for more information.

Instantiating an image

The images and kernel are public, so they do not require any registration. To start an instance, we use a command of the following form:

  • ec2-run-instances ami-xxxxx -k ${EC2_KEYPAIR} -t <instance type>

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

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.

  • ec2-terminate-instances <instance_id>

See Also


  1. The package byobu has an extension that allows to display a cost estimate on your host terminal session (1)

EC2StartersGuide (last edited 2014-11-20 04:31:40 by rcj)