Setting up the Tools

The command line tools are available as a ZIP file in the Amazon EC2 Resource Center. These tools are written in Java and include shell scripts for both Windows 2000/XP and Linux/Unix/Mac OSX. The ZIP file is self-contained; no installation is required. All you need to do is download it and unzip it.

Some additional setup is required in order for the tools to use your AWS account credentials. These are discussed next.

The command line tools depend on an environment variable (EC2_HOME) to locate supporting libraries. You'll need to set this environment variable before you can use the tools. This should be set to the path of the directory into which the command line tools were unzipped. This directory is named ec2-api-tools-A.B-rrrr (A, B and r are version/release numbers), and contains sub-directories named bin and lib.

On Linux/Unix you can set this environment variable as follows:

$ export EC2_HOME=<path-to-tools>  

On Windows the syntax is slightly different:

C:\> set EC2_HOME=<path-to-tools>  

In addition, to make your life a little easier, you probably want to add the tools' bin directory to your system PATH. The rest of this guide assumes this is the case.

On Linux/Unix you can update your PATH as follows:

$ export PATH=$PATH:$EC2_HOME/bin 

On Windows the syntax is slightly different:

C:\> set PATH=%PATH%;%EC2_HOME%\bin 

The command line tools need access to the private key and X.509 certificate you generated after signing up for the Amazon EC2 service.

Since there's nothing stopping you from having more than one AWS account you need to identify yourself to the command line API tools so they know which credentials to use for requests. It's possible, but tedious, to provide this information on the command line every time you invoke the tools. But it's far simpler to set up some environment variables and be done with it.

Two environment variables are supported to make this possible. They can be set to point at your private key and certificate. If these environment variables are set then the tools will use their values to find the relevant credentials. The environment variable EC2_PRIVATE_KEY should reference your private key file, and EC2_CERT should reference your X509 certificate.

On Linux/Unix you can set these environment variables as follows:

$ export EC2_PRIVATE_KEY=~/.ec2/pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem 
$ export EC2_CERT=~/.ec2/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem  

On Windows the syntax is slightly different:

C:\> set EC2_PRIVATE_KEY=c:\ec2\pk-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem 
C:\> set EC2_CERT=c:\ec2\cert-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem  

Congratulations!

You're ready to start using Amazon EC2.