Setting Up EC2 Command Line Tools on Windows

May 19th, 2009

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.

45 Responses to “Setting Up EC2 Command Line Tools on Windows”

  1. Amazon Elastic Load Balancer Setup | Serk Says:

    [...] Setting Up EC2 Command Line Tools on Windows [...]

  2. Chet34 Says:

    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

  3. Chet34 Says:

    my apologies , as usual user error ……. duh …

    where’s the any key ??

    thanks for the tutorial !!!

  4. Mike C Says:

    Thank you for publishing this article. It works great!

  5. raji Says:

    i am also gettin command unrecogized when I execute ec2 commands. How did u fix it?

  6. Chuck Donnelley Says:

    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.

  7. Steve Says:

    Chuck,

    From the command prompt can you type:

    %java_home%binjava.exe

    and not get an error message?

  8. Ec2 Links — Isaac's Blog Says:

    [...] http://LoudSteve.com/2009/05/19/setting-up-ec2-command-line-tools-on-windows/ [...]

  9. Hitesh Says:

    Thanks,

    I was faffinf around with AWS documentation and getting no where. But your article did it for me.
    Hitesh

  10. Dave Says:

    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

  11. Dave Says:

    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?

  12. Steve Says:

    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.

  13. Dave Says:

    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.

  14. Dave Says:

    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

  15. Steve Says:

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

  16. Alan Says:

    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

  17. Jonathan Hartley Says:

    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.

  18. Jonathan Hartley Says:

    Oops. Figured it: Download ‘elb*’ tools from here:
    http://developer.amazonwebservices.com/connect/entry.jspa?externalID=2536&categoryID=251

    (as you specify on your next post. Thanks!)

  19. Jason Says:

    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 :)

  20. Dinesh Says:

    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

  21. DJ Says:

    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

  22. Seb Says:

    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.

  23. Phil Says:

    Thanks for writing this up – it’s the missing instructions that should come with the API download!

  24. bob Says:

    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″

  25. Rich W Says:

    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.

  26. Finder Says:

    Thanks, it works! Cool!

  27. zs Says:

    Thanks, and Thank-You Seb

  28. Greipur Says:

    Jebs, works great ! (Win7 x64)

  29. Brian K Says:

    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!

  30. Dr. Rajiv Ranjan Says:

    Thanks for this great tutorial. It is really helpful.

  31. Ricardo Says:

    Thanks so much … is works great !!! super usefull the tutorial …

  32. Himanshu Gupta Says:

    Thanks mate….this is flawless!! Fantastic Work….Thanks again :)

  33. LanceVD Says:

    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

  34. James Smith Says:

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

  35. How to: Import Virtual Machines Into Amazon with the Amazon EC2 API Tools | FatFrame Says:

    [...] you need to download the Amazon EC2 API Tools and set your environment variables. For Windows, see this guide. When you get to the portion with certificates, make sure you are using the certs from the x.509 [...]

  36. Bob Ren Says:

    Thank you, this documentation was simple and clean…good job

  37. Michael Picher Says:

    Great write-up.

    Like James, I just had to get rid of spaces on the end of the following lines:

    set EC2_HOME=c:awsec2
    and
    set AWS_ELB_HOME=c:awselb

    Thanks!
    Mike

  38. Chris ODaniel Says:

    Thank you the white space was my only problem.

  39. Thomas Hackett Says:

    Even when using “setx”, test command didn’t work till I rebooted.

  40. Darren Plant Says:

    A little tweaking, works fine, thankyou.

  41. Migrating a VMware VM to AWS | Messor Says:

    [...] S. (May 19, 2009). Setting up EC2 command line tools on Windows. Retrieved March 20, 2012 from http://LoudSteve.com/2009/05/19/setting-up-ec2-command-line-tools-on-windows/. matiasimc. (June 21, 2011). Re: VMWare Workstation VM import Windows 2008 R2 failing. Retrieved [...]

  42. Venky Says:

    Great job dude the issues by following the Amazon link are solved here and thank you for that…

  43. Matt Says:

    Awesome tutorial!

  44. P Says:

    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!

  45. Arun Says:

    I am getting this error “Required option ‘-O, –aws-access-key KEY’ missing (-h for usage)”