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.

Advertisements

45 thoughts on “Setting Up EC2 Command Line Tools on Windows

  1. have setup the batch file exactly as stated and still receiving “not recognized as an internal or external command, operable program or batch file.

    the only change made to your existing batch file was the drive letter of C instead of D. Used everything else exactly the same. File names etc..

    any help would be greatly appreciated.

    Thanks

    Like

  2. I’ve installed from the ground up on two different machines, win7-64 and xp-32. Same problem, “not recognized as a valid command” etc. New java installs on both. I’ve triple checked the bat file, even run it step by step with pause and checking the SET values. Any help would be appreciated, many hours invested.

    Like

  3. Hi thanks for your post. I am a bit frustrated because I had my environment setup and working but after a reboot things seem to have come undone.

    I am getting the “‘ec2-describe-regions’ is not recognized as an internal or external command” error.

    The thing is I am sure that all my paths are correct. I dropped a boo.bat file in my %EC2_HOME&bin folder and when I run boo, it find it and runs it. When I run java -version it responds correctly as well.

    It seems to me that it might be a file associatation issues? None of the scripts in the ec2_homebin have extensions, so how does windows know to run them with java?

    set JAVA_HOME=”C:Program FilesJavajre6″
    set EC2_PRIVATE_KEY=E:EC2ec2-keyspk-[[snip]].pem
    set EC2_CERT=E:EC2ec2-keyscert-[[snip]].pem
    set EC2_HOME=C:Appsec2-api-tools-1.3-51254
    set PATH=%PATH%;%EC2_HOME%bin

    Like

  4. Just as a follow up. The problem I am having is not path related because even if I specify the fully qualified path I still get the error. The trouble is not that it can not find the ec2-* files but that it does not recognize them as command files.

    The error I am getting is what you would get if you just typed “bob.txt” at a cmd prompt.

    ‘bob.txt’ is not recognized as an internal or external command,
    operable program or batch file.

    So I wonder what I did before to get the OS to recognize all those ec2- files as command files. They are bash scripts right? When I run bash at the cmd prompt it loads fine so my cygwin setup seems to be fine.

    could it be the declaration at the top of ec2-cmd?
    #!/usr/bin/env bash

    Looks like a comment but is it?

    Like

  5. Dave,

    The bin folder should contain a file called ‘ec2-describe-regions’ without an extension and another file called ‘ec2-describe-regions.cmd’. If you don’t have the cmd files then I would download the API again and unzip again.

    Like

  6. Mostly solved!

    First issue is that my OS is not recognizing the bash scripts as scripts. If I type:
    c:bash ec2-describe-regions

    It ran the script and provided the information I need to move forward. When I ran the script it told me that I needed to use unix stlye delims (eg. / vs ) in my paths.

    Eg.
    EC2_HOME=c:/ec2-tools
    EC2_CERT=
    EC2_PRIVATE_KEY=

    For now I can specify bash directly but it would be nice to be able to set the file association up again.

    Like

  7. Thats funny I don’t have the cmd version but it was working the other day without any issues.

    I think what happened is that when I first setup my environment I installed cygwin and that installation set up the right conditions but didn’t persist them so that when I rebooted everything stopped working.

    This is workign for me for now, but I will take your advice and update the tools soon.

    C:Usersdave>bash 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
    REGION ap-southeast-1 ec2.ap-southeast-1.amazonaws.com

    Like

  8. Dave,

    If your using cygwin then you would want to follow Unix based instructions. My instructions here are with the assumption you will use the windows command prompt (aka a DOS prompt).

    Like

  9. Wow, thank you, spent hours on AWS site, just trying to find something to assist, and your instructions worked a treat.

    Once I got the paths sorted of course 🙂

    Thanks

    Like

  10. Very dumb newbie question:

    Where do the commands that start ‘elb*’ come from, e.g. ‘elb-create-lb’ (this is for creating an AWS LoadBalancer.)

    I’ve downloaded the command-line tools in ‘ec2-api-tools.zip’, but all the executables in the bin directory there start with ‘exc2′. So all my’ec2*’ commands work just fine:

    > ec2ver
    1.3-53907 2010-06-15

    I’m on Windows.

    Like

  11. Thank you very much for this step-by-step … I’ve been running into one wall or another with this setup thanks to n00bn3ss with AWS. You pointed me in the right direction 🙂

    Like

  12. Few things which I double checked to “troubleshoot” this EC2-API-tools not working in windows issue were :-

    1. My API tools folder didn’t have .cmd files …grrr…bad download!
    2. Had my AWS certificate in filename aws-cert.pem while batch file had aws-cer.pem (extra aplhabet ‘t’) variable. silly!
    3. There was an extra space character in batch file so when I ran echo %PATH% on cmdline I was getting C:awsec2 bin (notice the extra spca and break caused by it in path…again…double grrrr).
    4. Finally the command ran…and lo n behold….java exceptions…(soemthing to do with my certificate copying…the grrrrr’s continue)

    thanks
    Dinesh

    Like

  13. need help with command line
    i want to launch 5 instance using image (ami), key pair, in vpc, and with new name (host name)

    Please help

    Like

  14. Thanks for the writeup.

    Be careful if you copy-paste the batch file text, there are blank spaces after the ‘set PATH=….’ lines that you need to remove. Type ‘path’ in the commandline to check your path.

    These blank spaces will result in the ‘not recognized…’ error.

    Like

  15. If you’re having problems like “command not found”, try putting quotes around the absolute paths in the script.
    eg change

    set EC2_HOME=d:awsec2

    to

    set EC2_HOME=”d:awsec2″

    Like

  16. IMPORTANT –

    For error “not recognized as an internal or external command, operable program or batch file” check Dinesh’s post #21, item 3:

    “There was an extra space character in batch file so when I ran echo %PATH% on cmdline I was getting C:awsec2 bin (notice the extra spca and break caused by it in path…again…double grrrr).”

    This was my problem too. Copy and paste can hurt if you’re not careful.

    Like

  17. I was following the instructions and it appears everything is working, but when I run the ec2-describe regions, I get an error stating unkown host: “https://ec2.amazonaws.com”

    What am I missing? Any command I try gives me the same message.

    Thanks!

    Like

  18. Environment errors:
    Ensure there are no trailing spaces if you create the .bat, as it will muck things up.

    In a command window, type: set
    You should see not see any spaces in your PATH= section.
    Good: ;c:awselbbin;c:awsec2bin
    Bad: ;c:awselbbin;c:awsec2 bin

    Like

  19. Great article. I had trouble with whitespace in my batch file. Once I cleared that up, I can move to the next step.

    Like

  20. As Seb posted earlier. Be careful if you copy-paste the set variables. Remove any trailing spaces to avoid problems.

    Apart from that great tutorial!

    Like

Comments are closed.