Loading

Wednesday, December 16, 2009

Installing EC2 Command Line Tools on Windows

UPDATE (12-2016): See HowTo: Install AWS CLI on Both Windows and Linux for updated information on installing, configuring and using the AWS CLI unified tools.

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.

Prerequisite
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.zip
wget http://ec2-downloads.s3.amazonaws.com/ElasticLoadBalancing-2009-05-15.zip
wget http://s3.amazonaws.com/ec2-downloads/ec2-ami-tools.zip
Alternatively 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:
c:\admin\aws\ec2-api-tools
c:\admin\aws\ec2-elb-tools
c:\admin\aws\ec2-ami-tools


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-.pem) and a Certificate (cert-.pem).

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. 

Method 1
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
set EC2_HOME=C:\Admin\AWS\ec2-api-tools
set PATH=%PATH%;%EC2_HOME%\bin

REM Path to ELB API, subfolders of bin and lib
set AWS_ELB_HOME=C:\Admin\AWS\ec2-elb-tools
set PATH=%PATH%;%AWS_ELB_HOME%\bin

REM Path to EC2 AMI, subfolders of bin and lib
set AWS_AMI_HOME=C:\Admin\AWS\ec2-ami-tools
set PATH=%PATH%;%AWS_AMI_HOME%\bin

cls
cmd

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 - 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
JAVA_HOME needs to be set to the appropriate path for your machine.

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”:
c:\admin\aws>ec2-describe-regions
Results:
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-.pem) and Certificate (cert-.pem) file replacing my existing ones, and, viola, I was back in action.

UPDATE (12-2016): See HowTo: Install AWS CLI on Both Windows and Linux for updated information on installing, configuring and using the AWS CLI unified tools.

Commands Documentation
Amazon documentation.

Related

8 comments:

  1. What I'm unclear about here and what i've found is that there are additional prerequisites to get the ami tools to actually run on Windows. Can you confirm what those might be? I've got a few VMware images that i've worked hard to customize and would like to get those bundled into AMI's and into EC2. Can you suggest a process for this or at least note any additional prereqs for getting the amitools to work withing Windows?

    ReplyDelete
  2. Ivan, these instructions have worked well for me several times on Windows 7 and Windows 2003. I refer to them anytime I need to install the Amazon tools. While I haven't done it for a while I know they work. Hope this helps.

    ReplyDelete
  3. Interesting that the AMI ZIP only contains Unix scripts, and not windows - as Ivan said. I wonder why Amazon missed these out?

    ReplyDelete
  4. It seems that the ami tool are NOT working on windows without all the prerequisites or at least Ruby.
    When i try all the ami command on windows , nothing happenes and when i look in the file , it seems to try to start a ruby program. So I think that you at least need to hve Ruby installed on windows.

    ReplyDelete
  5. I had the same issue. If the AMI tools work on Windows I haven't gotten it to work with the above (nice instructions though for API Tools).

    Any help is appreciated.

    ReplyDelete
    Replies
    1. You have to create a .bat for each item in the /bin folder ie: ec2-unbundle needs a bat associated with it:

      --START BAT
      @echo off

      setlocal

      REM Copyright 2006-2010 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the
      REM Amazon Software License (the "License"). You may not use this file except in compliance with the License. A copy of the
      REM License is located at http://aws.amazon.com/asl or in the "license" file accompanying this file. This file is distributed on an "AS
      REM IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
      REM language governing permissions and limitations under the License.

      REM Set intermediate env vars because the %VAR:x=y% notation below
      REM (which replaces the string x with the string y in VAR)
      REM doesn't handle undefined environment variables. This way
      REM we're always dealing with defined variables in those tests.
      set CHK_HOME=_%EC2_HOME%

      if "%CHK_HOME:"=%" == "_" goto HOME_MISSING

      "%EC2_HOME:"=%\bin\ec2-cmd" ActivateLicense %*
      goto DONE
      :HOME_MISSING
      echo EC2_HOME is not set
      exit /b 1

      :DONE

      --END BAT

      Save in the /bin directory as ec2-unbundle.bat.

      Hope this helps someone in the future.

      Delete
  6. This video show help you: http://www.smattie.com/2012/06/16/ec2-windows-command-line-tools-installation/

    ReplyDelete
  7. Hi, I performed the above steps on Windows 7 64 bit machine but its not working. I get the below error. Something might be conflicting on the environment variables.

    c:\>%JAVA_HOME%\bin\java -version
    'C:\Program' is not recognized as an internal or external command,
    operable program or batch file.

    c:\>

    c:\>elb-describe-lbs
    'elb-describe-lbs' is not recognized as an internal or external command,
    operable program or batch file.

    c:\>elb-cmd
    'elb-cmd' is not recognized as an internal or external command,
    operable program or batch file.

    c:\>

    ReplyDelete