Did this page help you? Yes No Tell us about it...

Setting Up the Tools

Topics

Before you'll be able to use Amazon EC2, you need to download the command line tools and set them up to use your AWS account.

API Tools vs. AMI Tools

The command line tools are also called the API tools because they wrap the EC2 API, and to help distinguish them from the AMI tools, which are a set of tools for creating (bundling) and migrating certain types of AMIs. In this documentation, the term command line tools is equivalent to API tools.

The sections that follow describe how to set up the command line tools (API tools). If you find that you need the AMI tools for your particular situation, be aware that many AMIs already have the AMI tools installed. However, if you still need to download them, go to Amazon EC2 AMI Tools.

Where to Get the Command Line Tools (API Tools)

The command line tools (API tools) are available as a ZIP file in the Amazon EC2 API Tools. These tools are written in Java and include shell scripts for both Windows and Linux/UNIX/Mac OSX. The ZIP file is self-contained; no installation is required. Simply download the file and unzip it.

Tell the Tools Where They Live

The command line tools depend on environment variable EC2_HOME to locate supporting libraries. Before using the tools, set EC2_HOME to the directory path where the command line tools were unzipped.

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 can add the tools' bin directory to your system PATH. The rest of this guide assumes you have done so.

On Linux and UNIX, you can update your PATH as follows.

$ export PATH=$PATH:$EC2_HOME/bin

	Note
	The `export` command applies only to the current shell session. To permanently create or update an environment variable, include the command in a start-up script. For example, if you use Bash shell, you can include commands in your `~/.bashrc` or `/etc/profile` file.

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 with the `setx` command.

Tell the Tools Who You Are

The command line tools need access to the private key and X.509 certificate for your AWS account. For more information, see How to Create an X.509 Certificate and Private Key.

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. It's far simpler to set up some environment variables and be done with it.

There are two environment variables you can set up. They can be set to point at your private key and certificate. After you set these environment variables, 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-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem 
$ export EC2_CERT=~/.ec2/cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

On Windows the syntax is slightly different.

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

Set the Service Endpoint URL

By default, the Amazon EC2 tools use the US-East (Northern Virginia) Region (us-east-1) with the ec2.us-east-1.amazonaws.com service endpoint URL. This section describes how to specify a different Region by setting the service endpoint URL.

	Note
	Amazon EC2 prices vary by Region. For information about pricing, go to Amazon EC2 Pricing.

To set the service endpoint URL

View available Regions with the ec2-describe-regions command.

PROMPT> ec2-describe-regions
REGION  ap-northeast-1       ec2.ap-northeast-1.amazonaws.com
REGION  ap-southeast-1       ec2.ap-southeast-1.amazonaws.com
..

The result shows the Region names and corresponding service endpoints.

Set the service endpoint URL using one of the following commands:

For Linux and UNIX:

$ export EC2_URL=https://<service_endpoint>

For Windows:

C:\> set EC2_URL=https://<service_endpoint>

Where to Go from Here

For an overview of using Amazon EC2 with the command line tools, follow the instructions under Launching and Using Instances:

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...