Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-09-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

Setting Up the Amazon EC2 Command Line Interface Tools on Linux/Unix and Mac OS X

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, OS X, or Unix.

Note

Alternatively, you can use the AWS Command Line Interface (AWS CLI), which provides commands for a broad set of AWS products, including Amazon EC2. To get started with the AWS CLI, see the AWS Command Line Interface User Guide. For more information about the AWS CLI commands for Amazon EC2, see ec2 in the AWS Command Line Interface Reference.

Before you can use the Amazon EC2 CLI tools on your computer or your instance, you must install the tools and set the environment variables used by the tools. Use the set of directions for your operating system:

Setting Up the Amazon EC2 CLI Tools on Amazon Linux

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

Each time you use the Amazon EC2 CLI tools on your instance, you must provide your identity. Your access keys identify you to the Amazon EC2 CLI tools. There are two types of access keys: access key IDs and secret access keys. You should have stored your access keys in a safe place when you created them. Although you can retrieve your access key ID from the Your Security Credentials page, you can't retrieve your secret access key. Therefore, if you can't find your secret access key, you'll need to create new access keys before you can use the CLI tools.

The easiest way to provide your access keys to the Amazon EC2 CLI is to set the AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables. First, add the following lines to ~/.bashrc and save the file.

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

After you've updated ~/.bashrc, run the following command:

source ~/.bashrc

To verify that your CLI tools are set up correctly, run the following command:

ec2-describe-regions

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.

The default region for the Amazon EC2 CLI tools is us-east-1. For information about configuring the Amazon EC2 CLI tools to use a different region, see (Optional) Set the Region.

Setting Up the Amazon EC2 CLI Tools on RHEL, Ubuntu, or Mac OS X

You must complete the following setup tasks before you can use the Amazon EC2 CLI tools on your own computer.

Download and Install the CLI Tools

To download and install the CLI tools

  1. Download the tools. The CLI tools are available as a .zip file on this site: Amazon EC2 CLI Tools. You can also download them with the wget utility.

    wget http://s3.amazonaws.com/ec2-downloads/ec2-api-tools.zip
  2. (Optional) Verify that the CLI tools package has not been altered or corrupted after publication. For more information about authenticating the download before unzipping the file, see (Optional) Verify the Signature of the CLI Tools Download.

  3. Unzip the files into a suitable installation directory, such as /usr/local/ec2.

    sudo mkdir /usr/local/ec2
    sudo unzip ec2-api-tools.zip -d /usr/local/ec2

    Notice that the .zip file contains a folder ec2-api-tools-x.x.x.x, where x.x.x.x is the version number of the tools (for example, ec2-api-tools-1.7.0.0).

Tell the Tools Where Java Lives

The Amazon EC2 CLI tools require Java. If you don't have Java 1.7 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 X

  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

    If the previous command does not return a location for the Java binary, you need to install Java. For help installing Java on your platform, see Java Downloads.

    To install Java on Ubuntu systems, execute the following command:

    ubuntu:~$ sudo apt-get install -y openjdk-7-jre
  2. Find the Java home directory on your system. The which java command executed earlier returns Java's location in the $PATH environment variable, but in most cases this is a symbolic link to the actual program; symbolic links do not work for the JAVA_HOME environment variable, so you need to locate the actual binary.

    1. (Linux only) For Linux systems, you can recursively run the file command on the which java output until you find the binary.

      $ file $(which java)
      /usr/bin/java: symbolic link to `/etc/alternatives/java'

      The /usr/bin/java location is actually a link to /etc/alternatives/java, so you need to run the file command on that location to see whether that is the real binary.

      $ file /etc/alternatives/java
      /etc/alternatives/java: symbolic link to `/usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java'

      This returns a new location, which is the actual binary. Verify this by running the file command on this location.

      $ file /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
      /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java: ELF 64-bit LSB executable...

      This location is the actual binary (notice that it is listed as an executable). The Java home directory is where bin/java lives; in this example, the Java home directory is /usr/lib/jvm/java-7-openjdk-amd64/jre.

    2. (Mac OS X only) For Mac OS X systems, the /usr/libexec/java_home command returns a path suitable for setting the JAVA_HOME variable.

      $ /usr/libexec/java_home
      /System/Library/Java/JavaVirtualMachines/1.7.0_55.jdk/Contents/Home
  3. Set JAVA_HOME to the full path of the Java home directory.

    1. (Linux only) For the Linux example above, set the JAVA_HOME variable to the directory where bin/java was located in Step 2.a.

      $ export JAVA_HOME="/usr/lib/jvm/java-7-openjdk-amd64/jre"

      Note

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

    2. (Mac OS X only) For the Mac OS X example above, set the JAVA_HOME variable to $(/usr/libexec/java_home). The following command sets this variable to the output of the java_home command; the benefit of setting the variable this way is that it updates to the correct value if you change the location of your Java installation later.

      $ export JAVA_HOME=$(/usr/libexec/java_home)
  4. 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_55"
    OpenJDK Runtime Environment (IcedTea6 2.4.7) (7u55-2.4.7-1ubuntu0.12.04.2)
    OpenJDK 64-Bit Server VM (build 24.51-b03, mixed mode)
  5. Add this environment variable definition to your shell start up scripts so that it is set every time you log in or spawn a new shell. The name of this startup file differs across platforms (in Mac OS X, this file is commonly called ~/.bash_profile and in Linux, it is commonly called ~/.profile), but you can find it with the following command:

    $ ls -al ~ | grep profile

    If the file does not exist, you can create it. Use your favorite text editor to open the file that is listed by the previous command, or to create a new file with that name. Then edit it to add the variable definition you set in Step 3.

  6. Verify that the variable is set properly for new shells by opening a new terminal window and testing that the variable is set with the following command.

    Note

    If the following command does not correctly display the Java version, try logging out, logging back in again, and then retrying the command.

    $ $JAVA_HOME/bin/java -version

Tell the CLI Tools Where They Live

The Amazon EC2 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 them. 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 CLI tools to your system path. The examples in the Amazon EC2 User Guide for Linux Instances assume that you have done so.

You can set the EC2_HOME and PATH environment variables as follows. Add them to your shell start up scripts so that they're set every time you log in or spawn a new shell.

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

  1. Use this command to set the EC2_HOME environment variable. For example, if you unzipped the tools into the /usr/local/ec2 directory created earlier, execute the following command, substituting the correct version number of the tools.

    $ export EC2_HOME=/usr/local/ec2/ec2-api-tools-1.7.0.0  

    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

Your access keys identify you to the Amazon EC2 CLI tools. There are two types of access keys: access key IDs (for example, AKIAIOSFODNN7EXAMPLE) and secret access keys (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). You should have stored your access keys in a safe place when you received them. Although you can retrieve your access key ID from the Your Security Credentials page or the IAM console (if you are an IAM user), you can't retrieve your secret access key. Therefore, if you can't find your secret access key, you'll need to create or request new access keys before you can use the CLI tools.

Every time you issue a command, you must specify your access keys using the --aws-access-key and --aws-secret-key (or -O and -W) options. Alternatively, you might find it easier to store your access keys 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. You can add them to your shell startup scripts so that they're set every time you log in or spawn a new shell.

You can set these environment variables as follows.

export AWS_ACCESS_KEY=your-aws-access-key-id 
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 Amazon EC2 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)
http.nonProxyHostsA list of hosts that should be reached directly, bypassing the proxy. Each item in the list is separated by '|'.

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 Amazon EC2 CLI tools are set up correctly. Run the following command to view your available regions.

$ ec2-describe-regions

If your environment variables are set correctly, the output lists regions and their 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.

If you get a Client.AuthFailure error, check that you've entered your AWS_ACCESS_KEY and AWS_SECRET_KEY correctly, and check that the date and time are set correctly on your computer.

(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 CLI, 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.