Setting up the Tools

Topics

One step remains before you'll be able to use Amazon EC2. You need to get our command line tools and set them up to use your AWS account.

How to Get the Command Line 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. You just 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.

How to Tell the Tools Where They Live

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-nnnn (A, B and n are version/release numbers), and contains sub-directories named bin and lib.

On Linux and 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 is done.

On Linux and 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

	Note
	The Windows environment variables are reset when you close the command window. You might want to set them permanently.

How to Tell the Tools Who You Are

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

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, the tools 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 X.509 certificate.

On Linux and 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

How to Change the Region

By default, the Amazon EC2 tools use the Eastern United States region (us-east-1) with the us-east-1.ec2.amazonaws.com service endpoint. This section describes how to specify a different region.

To specify a different region

View available regions by entering the following:

PROMPT> ec2-describe-regions

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

If you want to change the service endpoint on Linux and UNIX, set the EC2_URL environment variable as follows:
```
$ export EC2_URL=https://<service_endpoint>  
```
If you want to change the service endpoint on Windows, set the EC2_URL environment variable as follows:
```
C:\> set EC2_URL=https://<service_endpoint>  
```

You're ready to start using Amazon EC2.