NOTE: This tutorial contains information for both AMI and API command line tools along with ELB tools. Most users will need the API tools, some the ELB tools, and not many will need the AMI tools.
There are a number of GUI tools for working with Amazon EC2 services such as ElasticFox, RightScale and AWS Management Console. However often you need to use the command line tools because you want to script a task, or access features that a GUI tool doesn’t provide.
There are several guides and tutorials on installing and configuring the command line tools on Linux, but not much for Windows. So this aims to be THE GUIDE to setting up the EC2 API, ELB and EC2 AMI command line tools on Windows.
The first requirement is to have Java 5 or later installed. If you don’t already have it download and install from here.
AWS Command Line Tools Directory
I like to organize my programs a certain way so I installed the tools to c:\admin\aws. You can install the tools wherever you like. Note, this is where you may store your certificates, the services API files, etc.
Download Amazon command line tools
I used wget (for Windows) to download the files:
wget http://s3.amazonaws.com/ec2-downloads/ec2-api-tools.zipAlternatively you could download one or both directly from your browser. EC2 API Tools. ELB Tools. EC2 AMI Tools.
Unzip all three files. Each will unzip to separate directories, usually including the version number of the tool. To simplify things I moved all files from their respective locations to the following directories:
Retrieve and Store AWS Certificates
Authentication to AWS uses a certificate and private key. You will have to retrieve these files from AWS.
Logon to the AWS Console and scroll down to the X.509 area. You may have to create a new certificate. Once you do Amazon will provide you a Private Key File (pk-
KEEP THESE FILES PRIVATE. Possession of these two files give you (or anyone else with them) access to your AWS account.
Configure Environment Variables
You need to configure your command line environment with a few environment variables.
This method is used to launch a command prompt with required settings. These settings are available only for this session. If you'd like to configure your system to have these settings available always and system-wide use method 2.
Create a batch file in c:\admin\aws called awsTools.bat. Edit this file with the following text:
REM Path should contain bin\java.exe
set JAVA_HOME="C:\Program Files (x86)\java\jre6"
REM Path to Primary Key and Certificate retrieved from AWS
set EC2_PRIVATE_KEY=C:\Admin\AWS\pk-<Insert your key name here>.pem
set EC2_CERT=C:\Admin\AWS\cert-<Insert your key name here>.pem
REM Path to EC2 API, subfolders of bin and lib
REM Path to ELB API, subfolders of bin and lib
REM Path to EC2 AMI, subfolders of bin and lib
Note: Make sure none of the path statements in this file end with a trailing slash.
Configure Environment Variables - Method 2
This method adds the necessary system variables to either your profile or system-wide and makes them available anytime you launch a command prompt. Open the environment variables dialogue (right-click on My Computer, select System Properties, click Advanced tab, then Environment Variables button). Add the following to either your user account or system variables section depending on your needs.JAVA_HOME needs to be set to the appropriate path for your machine.
Explanation of System Variables
- JAVA_HOME - C:\Program Files (x86)\java\jre6
- EC2_PRIVATE_KEY - C:\Admin\AWS\pk-<Insert your key name here>.pem
- EC2_CERT - C:\Admin\AWS\cert-<Insert your key name here>.pem
- EC2_HOME - C:\Admin\AWS\ec2-api-tools
- AWS_ELB_HOME - C:\Admin\AWS\ec2-elb-tools
- AWS_AMI_HOME - C:\Admin\AWS\ec2-ami-tools
- Add ;C:\Admin\AWS\ec2-api-tools\bin;C:\Admin\AWS\ec2-elb-tools\bin;C:\Admin\AWS\ec2-ami-tools\bin to your path
Explanation of System Variables
For example on my (64-bit Window 7) system java.exe is located at “C:\Program Files (x86)\java\jre6\bin\java.exe” so I set JAVA_HOME to “C:\Program Files (x86)\java\jre6”
EC2_Private_Key and EC2_Cert both are the location of the private key and certificate that you retrieved from the AWS website in the previous step. You could rename the key and certificate for simplification. If you have multiple AWS accounts all you need to do is modify these lines to switch between accounts.
EC2_HOME and AWS_ELB_HOME both point to the folders you unzipped the API into. Both folders should have two subdirectories called bin and lib. Bin will contain the cmd files of the different commands for that API. You set the path variable to include these cmd files in your path so that you do not have to be in that directory to run them.
Now you only need to run the batch file to get a command line with the environmental variables set. You also could permanently set these variables and have them available in any command window if you choose. If you want to get fancy you could even put in the logic to set the paths based on the current directory of the batch file, and then put the folder on a thumb drive and carry it around.
Testing Your Setup
If you run awsTools.bat you should have a command prompt where you can run the EC2 tool. A simple command to test is “ec2-describe-regions”:
REGION eu-west-1 ec2.eu-west-1.amazonaws.com
REGION us-east-1 ec2.us-east-1.amazonaws.com
REGION us-west-1 ec2.us-west-1.amazonaws.com
If you receive an error running this command then you need to go back and verify your installation.
UPDATE: Recently I had to change my Amazon access credentials and created a new X.509 certificate. When I tried to run any commands from the command line I received the message, "Client.AuthFailure: AWS was not able to validate the provided access credentials." So I just downloaded my new Private Key File (pk-