Setting Up EC2 Command Line Tools on Windows

There are some great GUI tools for working with EC2 services such as ElasticFox and AWS Management Console.

And that’s just the tip of the iceberg.  However sometimes 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 access to.  For example today I became motivated to finally get comfortable with the EC2 API so I could create a Elastic Load Balancer instance to test the new functionality provided.

I found lots of tutorials and guidance on setting up your Linux machine to run the tools.  Unfortunately Windows is a 2nd class citizen on AWS.  This is true pretty much across the board from command line tools, to Windows instances (just made available last October, still on Win2k3, etc).

So here is the “definitive guide” to setting up your Windows machine to run the EC2 API command line tools:

Install Java

The first requirement is to have Java 5 or later installed.  If you don’t already have Java installed for some reason go to http://www.java.com/en/download/manual.jsp#win.

Decide on AWS Root

Create a folder called AWS somewhere.  I like to make it easy to get to so I created it at d:aws.  You can really call this folder whatever you want, but it will be where you store your certificates, your services API files, etc.

Retrieve and Store AWS Certificates

Authentication to AWS happens via a certificate and private key.  You’ll need to retrieve these files from AWS.

Go to http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key and then scroll down to the X.509 area.  You’ll need to create a new certificate.  Once you do they’ll provide you a Private Key File (pk-<random characters>.pem) and a Certificate (cert-<random characters>.pem).

KEEP THESE FILES PRIVATE.  Possession of these two files give you access to your AWS account.

Configure Environment Variables

Now you need to configure your command line environment with a few environment variables.  Create a batch file in d:aws called awsTools.bat.  Edit this file with the following text:

REM Path should have binjava.exe under it
set JAVA_HOME="C:Program Files (x86)javajre6"

REM Path to Primary Key and Certificate retrieved from AWS
set EC2_PRIVATE_KEY=d:awsaws-pk.pem
set EC2_CERT=d:awsaws-cer.pem

REM Path to EC2 API, subfolders of bin and lib
set EC2_HOME=d:awsec2
set PATH=%PATH%;%EC2_HOME%bin

REM Path to ELB API, subfolders of bin and lib
set AWS_ELB_HOME=D:awselb
set PATH=%PATH%;%AWS_ELB_HOME%bin

cls

cmd

On all of the paths be careful about not including a trailing slash.

JAVA_HOME will need to be set to the appropriate path for your machine.  If you’re confused about where exactly JAVA_HOME should point to find java.exe.  It will be a in a folder called bin.  You want to set JAVA_HOME to the parent directory of bin.

For example on my system you would find java.exe at “C:Program Files (x86)javajre6binjava.exe” so I set JAVA_HOME to “C:Program Files (x86)javajre6”

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.  I renamed my key and certificate for simplicities sake.  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.

Test Command

If you run awsTools.bat you should have a command prompt that you can run the EC2 tools from.  A simple command to test is “ec2-describe-regions”:

D:aws>ec2-describe-regions

REGION  eu-west-1     eu-west-1.ec2.amazonaws.com

REGION  us-east-1     us-east-1.ec2.amazonaws.com

If you get an error running this command then you need to go back and verify your installation.

Commands Documentation

I have found the Quick Reference Cards provided by Amazon to be extremely useful.  They can be found at http://aws.amazon.com/documentation/ for all the various services.