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 Windows

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.

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

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

Note

These instructions are written for a Windows 7 client. What you need to do to complete some tasks may vary if you're using a different version of Windows.

Task 1: Download the Command Line Interface Tools (CLI Tools)

The CLI tools are available as a .zip file on the Amazon EC2 CLI Tools site. The tools are written in Java and include shell scripts for both Windows and Linux/UNIX/Mac OSX. The .zip file is self-contained; no installation is required. You can simply download the file and unzip it.

(Optional) You can 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.

Task 2: Set the JAVA_HOME Environment Variable

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

To set the JAVA_HOME environment variable on your computer or instance

  1. 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 Free Java Download.

  2. Set JAVA_HOME to the full path of the Java home. For example, if your Java executable is in C:\Program Files (x86)\Java\jre7\bin, set JAVA_HOME to C:\Program Files (x86)\Java\jre7.

    Important

    These steps don't update the environment variables in your current Command Prompt windows. The Command Prompt windows that you open after you complete these steps will contain the updates. This is why it's necessary for you to open a new Command Prompt window to verify that your environment is set up properly.

    1. Click Start, right-click Computer, and then click Properties.

    2. Click Advanced system settings.

    3. Click Environment Variables.

    4. Under User variables, click New.

    5. In Variable name, type JAVA_HOME.

    6. In Variable value, type the path to your Java home (for example, C:\Program Files (x86)\Java\jre7).

      Important

      Don't include the bin folder in JAVA_HOME. This is a common mistake, but the CLI tools won't work if you do this.

    7. Click OK.

  3. Open a new Command Prompt window and verify your JAVA_HOME setting using this command:

    C:\> "%JAVA_HOME%"\bin\java -version

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

    java version "1.7.0_45"
    Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
    Java HotSpot(TM) Client VM (build 24.45-b08, mixed mode, sharing)

    Otherwise, check the setting of JAVA_HOME, fix any errors, open a new Command Prompt window, and try the command again.

  4. Add the bin folder that contains the Java executable to your path before other versions of Java.

    1. Return to the Environment Variables window. In User variables, select Path, and then click Edit. (If this environment variable doesn't exist, create it.)

    2. In Variable values, before any other versions of Java add ;%JAVA_HOME%\bin. Then click OK.

  5. Open a new Command Prompt window and verify your update to the Path environment variable using this command.

    C:\> java -version

    You should see the same output as before. Otherwise, check the setting of Path, fix any errors, open a new Command Prompt window, and try the command again.

Task 3: Set the EC2_HOME Environment Variable

The Amazon EC2 CLI tools read the EC2_HOME environment variable to locate supporting libraries. You'll need to set this environment variable to the path where you unzipped the CLI tools. This folder is named ec2-api-tools-w.x.y.z (where w, x, y, and z are components of the version number). It contains subdirectories named bin and lib.

To set the EC2_HOME environment variable on your computer or instance

  1. Set EC2_HOME to the path of the folder into which you unzipped the CLI tools.

    Important

    These steps don't update the environment variables in your current Command Prompt windows. The Command Prompt windows that you open after you complete these steps will contain the updates. This is why it's necessary for you to open a new Command Prompt window to verify that your environment is set up properly.

    1. Click Start, right-click Computer, and then click Properties.

    2. Click Advanced system settings.

    3. Click Environment Variables.

    4. Under User variables, click New.

    5. In Variable name, type EC2_HOME.

    6. In Variable value, type the path to the folder where you installed the CLI tools. For example, C:\AWS\EC2\ec2-api-tools-1.7.0.0. Click OK.

  2. Open a new Command Prompt window and verify your EC2_HOME setting using this command.

    C:\> dir "%EC2_HOME%"

    If you've set the environment variable correctly, you'll see output for the folder listing. If you get a File Not Found error, check the setting of EC2_HOME, fix any errors, open a new Command Prompt window, and try the command again.

  3. Add the bin folder for the tools to your system Path environment variable. The rest of this guide assumes that you've done this.

    You can update your Path as follows:

    1. Return to the Environment Variables window. In User variables, select Path, and then click Edit.

    2. In Variable values, add ;%EC2_HOME%\bin. Then click OK.

Task 4: Set the AWS_ACCESS_KEY and AWS_SECRET_KEY Environment Variables

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 command line.

The following procedure describes how to create environment variables that specify your access keys.

To set up your environment variables on your computer or instance

  1. Click Start, right-click Computer, and then click Properties.

  2. Click Advanced system settings.

  3. Click Environment Variables.

  4. Under User variables, click New.

  5. In Variable name, type AWS_ACCESS_KEY.

  6. In Variable value, specify your access key ID. Click OK.

  7. Under User variables, click New.

  8. In Variable name, type AWS_SECRET_KEY.

  9. In Variable value, specify your secret access key. Click OK.

To verify that all your environment variables are set up correctly, open a new Command Prompt window and run the following command.

C:\> ec2-describe-regions

If your environment variables are set correctly, you'll see output that looks something like this.

REGION  us-east-1       ec2.us-east-1.amazonaws.com
REGION  eu-west-1       ec2.eu-west-1.amazonaws.com
REGION  sa-east-1       ec2.sa-east-1.amazonaws.com
REGION  ap-northeast-1  ec2.ap-northeast-1.amazonaws.com
REGION  us-west-2       ec2.us-west-2.amazonaws.com
REGION  us-west-1       ec2.us-west-1.amazonaws.com
REGION  ap-southeast-1  ec2.ap-southeast-1.amazonaws.com

If you get an error that this command is not recognized as an internal or external command, check the setting of Path, fix any errors, open a new Command Prompt window, and try the command again.

If you get an error that required option -O is missing, check the setting of AWS_ACCESS_KEY, fix any errors, open a new Command Prompt window, 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, open a new Command Prompt window, 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.

Task 5: Set the Region (Optional)

By default, the Amazon EC2 CLI tools use the us-east-1 region with the ec2.us-east-1.amazonaws.com service endpoint URL. If your instances are in a different region, you must specify the region where your instances reside. For example, if your instances are in Europe, you must specify the eu-west-1 region by using the --region eu-west-1 option or by setting the EC2_URL environment variable.

This section describes how to specify a different region by changing the service endpoint URL.

To specify a different region on your computer or instance

  1. To view available regions, see Regions and Endpoints in the Amazon Web Services General Reference.

  2. To change the service endpoint, set the EC2_URL environment variable.

    The following example sets EC2_URL.

    1. Click Start, right-click Computer, and then click Properties.

    2. Click Advanced system settings.

    3. Click Environment Variables.

    4. Under User variables, click New.

    5. In Variable name, type EC2_URL.

    6. In Variable value, type https://ec2.eu-west-1.amazonaws.com. Click OK.

Task 6: Use a Proxy (Optional)

If the computer with the installed CLI tools 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 '|'.

To set up the EC2_JVM_ARGS environment variable on your computer or instance

  1. Click Start, right-click Computer, and then click Properties.

  2. Click Advanced system settings.

  3. Click Environment Variables.

  4. Under User variables, click New.

  5. In Variable name, type EC2_JVM_ARGS.

  6. In Variable value, specify the proxy configuration properties. For example, -Dhttps.proxyHost=my.proxy.com -Dhttps.proxyPort=8080. Then click OK.

Task 7: Download Remote Desktop

To connect to a Windows instance, you'll need a Remote Desktop client. The most recent versions of Windows include a Remote Desktop client already. To check whether you have one, open a Command Prompt window and type mstsc. If this command displays the Remote Desktop Connection window, you're set. Otherwise, go to the Microsoft Windows home page and search for the download for Remote Desktop Connection.

Now you're ready to start using Amazon EC2 from a Command Prompt window!