Amazon Elastic Compute Cloud
User Guide (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » User Guide » Setting Up the Amazon EC2 Command Line Interface Tools on Linux/UNIX
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Setting Up the Amazon EC2 Command Line Interface Tools on Linux/UNIX

The Amazon EC2 command line interface tools (also called the CLI tools) wrap the Amazon EC2 API actions. These tools are written in Java and include shell scripts for both Windows and Linux/UNIX/Mac OSX. For a detailed reference guide that describes the commands, see the Amazon Elastic Compute Cloud Command Line Reference.

Before you can use the Amazon EC2 CLI tools, you need to download them and configure them to use your AWS account. You can set up the tools on your own computer or on an Amazon EC2 instance.

Note

For more information about installing the CLI tools on Windows, see Installing the Amazon EC2 Command Line Interface Tools on Windows.

Complete the following tasks to set up an Amazon EC2 environment:

  1. Download the Command Line Interface Tools

  2. Get Your Access Key ID and Secret Access Key

  3. Set Up the Command Interface Line Tools

  4. Download an SSH Client

Download the Command Line Interface Tools

The CLI tools are available as a ZIP file on this site: Amazon EC2 CLI Tools. The ZIP file is self-contained; no installation is required. You can simply download the file and unzip it.

Important

Instances that you launch using the Amazon Linux AMI already include the CLI tools.

Optional step before you unzip: For detailed information about authenticating the download before unzipping the file, see Verify the Signature of the Tools Download.

Get Your Access Key ID and Secret Access Key

The access key ID and secret access key are the most commonly used set of AWS credentials. They are used to use the CLI and make Query requests. You can use up to two sets of access keys at a time. You can generate new keys at any time or disable existing keys.

To get your access key ID and secret access key

  1. Go to the Amazon Web Services web site at http://aws.amazon.com.

  2. Click My Account/Console, and then click Security Credentials.

    If you are not already logged in, you are prompted to do so.

  3. Under the Access Credentials section, ensure that the Access Keys tab is selected.

  4. Locate an active access key under Your Access Keys.

  5. To display the secret access key, click Show in the Secret Access Key column.

  6. Write down the keys or save them.

  7. If there are no access keys in the list, click Create a New Access Key and follow the on-screen prompts.

Set Up the Command Interface Line Tools

After you've downloaded the CLI tools, you must complete the following setup tasks before you can use them.

Topics

Tell the Tools Where Java Lives

The Amazon EC2 CLI tools require Java. If you don't have Java 1.6 or later installed, download and install Java. Either a JRE or JDK installation is acceptable. To view and download JREs for a range of platforms, see Java Downloads.

Important

Instances that you launch using the Amazon Linux AMI already include Java.

The Amazon EC2 CLI read the JAVA_HOME environment variable to locate the Java runtime. This environment variable should specify the full path of the directory that contains a subdirectory named bin that contains the Java executable you installed (java.exe).

To set the JAVA_HOME environment variable on Linux/UNIX and Mac OS

  1. You can verify whether you have Java installed and where it is located using the following command:

    $ which java

    The following is example output.

    /usr/bin/java

    Note that this location can be a symlink rather than the actual directory location. You can't use a symlink in an environment variable.

    In the default installation of Mac OS, Java is installed in /Library/JAVA/Home. If you installed Java manually, Java might be located elsewhere. For more information about setting this variable on a Mac, see Unable to find a $JAVA_HOME.

  2. Set JAVA_HOME to the full path of the Java home directory. For example, if your Java executable is in /usr/bin, set JAVA_HOME to /usr, as shown here.

    $ export JAVA_HOME=/usr

    Note

    The export command applies only to the current shell session. To permanently create or update an environment variable, include the command in a start-up script. For example, if you use Bash shell, you can include commands in your ~/.bashrc or /etc/profile file.

    Note

    If you are using Cygwin, JAVA_HOME should contain a Windows path.

  3. You can verify your JAVA_HOME setting using this command.

    $ $JAVA_HOME/bin/java -version

    If you've set the environment variable correctly, the output looks something like this.

    java version "1.7.0_05"
Java(TM) SE Runtime Environment (build 1.7.0_05-b05)
Java HotSpot(TM) Client VM (build 23.1-b03, mixed mode, sharing)

Tell the CLI Tools Where They Live

The CLI tools read the EC2_HOME environment variable to locate supporting libraries. Before using these tools, set EC2_HOME to the directory path where you unzipped the CLI tools. This directory is named ec2-api-tools-w.x.y.z (where w, x, y, and z are components of the version number). It contains sub-directories named bin and lib.

In addition, to make things a little easier, you can add the bin directory for the tools to your system path. The examples in the Amazon Elastic Compute Cloud User Guide assume that you have done so.

You can set the EC2_HOME and PATH environment variables as follows. The export command updates the current shell session only. To permanently set these environment variables, include these commands in the start-up script for your shell.

To set the EC2_HOME and PATH environment variables on Linux/UNIX

  1. Use this command to set the EC2_HOME environment variable.

    $ export EC2_HOME=<path-to-tools>

    Note

    If you are using Cygwin, EC2_HOME must use Linux/UNIX paths (for example, /usr/bin instead of C:\usr\bin). Additionally, the value of EC2_HOME cannot contain any spaces, even if the value is quoted or the spaces are escaped.

  2. You can update your PATH as follows.

    $ export PATH=$PATH:$EC2_HOME/bin

Tell the CLI Tools Who You Are

When you sign up for an AWS account, we create access credentials for you so that you can make secure requests to AWS. You must provide these credentials to the Amazon EC2 CLI tools so that they know that the commands that you issue come from your account. For more information, see Get Your Access Key ID and Secret Access Key.

You can specify these credentials with the --aws-access-key and --aws-secret-key (or -O and -W) options every time you issue a command. However, it's easier to store your access credentials using the following environment variables:

  • AWS_ACCESS_KEY—Your access key ID

  • AWS_SECRET_KEY—Your secret access key

If these environment variables are set properly, their values serve as the default values for these required options, so you can omit them from the commands.

Note

Although we don’t encourage it, for a limited time you can still use EC2_PRIVATE_KEY and EC2_CERT instead of AWS_ACCESS_KEY and AWS_SECRET_KEY. For more information, see Deprecated Options in Common Options for CLI Tools in the Amazon Elastic Compute Cloud Command Line Reference. If you specify both sets of credentials, the command line tools use the access key ID and secret access key.

You can set these environment variables as follows. The export command updates the current shell session only. To permanently set these environment variables, include these commands in the start-up script for your shell.

$ export AWS_ACCESS_KEY=your-aws-access-key 
$ export AWS_SECRET_KEY=your-aws-secret-key

(Optional) Tell the CLI Tools To Use a Proxy Server

If the computer you have installed the CLI tools on requires the use of a proxy server, you must tell the CLI tools to use the proxy server with the EC2_JVM_ARGS environment variable.

The following table contains the proxy configuration properties that can be set for the EC2_JVM_ARGS variable. The properties that are required will depend on the type of proxy server being used. For example, the http.proxyDomain and http.proxyWorkstation properties are only used with a Windows NTLM proxy.

PropertyDescription
https.proxyHostHTTPS proxy host. Use when EC2_URL specifies an HTTPS host.
https.proxyPortHTTPS proxy port. Use when EC2_URL specifies an HTTPS host.
http.proxyHostHTTP proxy host. Use when EC2_URL specifies an HTTP host.
http.proxyPortHTTP proxy port. Use when EC2_URL specifies an HTTP host.
http.proxyDomainProxy domain (HTTPS and HTTP)
http.proxyWorkstationProxy workstation (HTTPS and HTTP)
http.proxyUserProxy user name (HTTPS and HTTP)
http.proxyPassProxy password (HTTPS and HTTP)

You set the EC2_JVM_ARGS variable with the export command:

export EC2_JVM_ARGS="-Dhttps.proxyHost=my.proxy.com -Dhttps.proxyPort=8080"

Verify the Tools Setup

Let's quickly verify that your CLI tools are set up correctly. Run the following command to view your available regions.

PROMPT> ec2-describe-regions
REGION us-east-1  ec2.us-east-1.amazonaws.com
REGION  ap-northeast-1  ec2.ap-northeast-1.amazonaws.com
REGION  ap-southeast-1  ec2.ap-southeast-1.amazonaws.com
..

The result shows the region names and corresponding service endpoints.

If you get an error that required option -O is missing, check the setting of AWS_ACCESS_KEY, fix any errors, and try the command again.

If you get an error that required option -W is missing, check the setting of AWS_SECRET_KEY, fix any errors, and try the command again.

(Optional) Set the Region

By default, the Amazon EC2 CLI tools use the US East (Northern Virginia) region (us-east-1) with the ec2.us-east-1.amazonaws.com service endpoint URL. To access a different region with the CLI tools, you must set the EC2_URL environment variable to the proper service endpoint URL.

To set the service endpoint URL

  1. To list your available service endpoint URLs, call the ec2-describe-regions command, as shown in the previous section.

  2. Set the EC2_URL environment variable using the service endpoint URL returned from the ec2-describe-regions command as follows.

    $ export EC2_URL=https://<service_endpoint>

If you've already launched an instance using the console and wish to work with the instance using the command line interface, you must specify the endpoint URL for the instance's region. You can verify the region for the instance by checking the region selector in the console navigation bar.

For more information about the regions and endpoints for Amazon EC2, see Regions and Endpoints in the Amazon Web Services General Reference.

Download an SSH Client

To connect to a Linux instance, you'll need an SSH client. Most Linux and UNIX installations include an SSH client by default. If yours doesn't, the OpenSSH project provides a free implementation of the full suite of SSH tools. For more information, see http://www.openssh.org.

Windows users can download and install PuTTY, a free SSH client. To download the client and installation instructions, go to http://www.chiark.greenend.org.uk/~sgtatham/putty/. For information about how to use PuTTY with Amazon EC2, see Connecting to Linux/UNIX Instances from Windows Using PuTTY.

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...