Installing the Amazon EC2 Command Line Interface Tools on Windows

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

The CLI tools are available as a ZIP file on this site: Amazon EC2 CLI Tools. 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.

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 directory that contains a subdirectory 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.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 Free Java Download.

2. Set JAVA_HOME to the full path of the Java home directory. 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 System variables, click New.

   5. In Variable name, type JAVA_HOME.

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

      Important

      Don't include the bin directory 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_05"
Java(TM) SE Runtime Environment (build 1.7.0_05-b05)
Java HotSpot(TM) Client VM (build 23.1-b03, 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 directory that contains the Java executable to your path before other versions of Java.

1. 1. In System variables, select Path, and then click Edit.

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

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

To set the EC2_HOME environment variable on your computer or instance

1. Set EC2_HOME to the path of the directory 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 System variables, click New.

   5. In Variable name, type EC2_HOME.

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

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 directory 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 directory 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. In System variables, select Path, and then click Edit.

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

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

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 System variables, click New.

5. In Variable name, type AWS_ACCESS_KEY.

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

7. Under System variables, click New.

8. In Variable name, type AWS_SECRET_KEY.

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

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.

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-1option 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 System variables, click New.

   5. In Variable name, type EC2_URL.

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

Task 6: Use a Proxy (Optional)

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.

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 System 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".

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!