Using AWS Command Line Tools

The following section instructs on setting up your environment for using AWS Auto-Scaling command line tools. A Java 5 compatible Java Runtime Environment is needed. Also, Windows instances require a Remote Desktop Access client, while Linux and UNIX instances require access to an SSH client. You can refer to the two following sections for more information on this. Conventionally, command line text is always prefixed with a generic command line prompt (PROMPT>). An actual command line prompt on a computer might be different. The sign $ is used to indicate Linux or UNIX-specific commands, and C:\> is used for commands specific to Windows. Although explicit instructions are not provided, the tools also work well on Mac OS X. The resulting example output from the command has been shown immediately thereafter, and without any prefix.

Setting the Java Home Variable

To run Auto-Scaling command line tools Java Runtime Environment (JRE) 5 or later is required. Both JRE and JDK installations are acceptable. To download JREs for Windows, Linux/UNIX, and various other platforms, please visit to http://java.sun.com/j2se/1.5.0/.

Command line tools depend on an environment variable to locate Java runtime. This environment variable (JAVA_HOME) should be set to the full path of the Java executable file (java.exe for Windows, and java for Linux/Unix). You should make sure that the bin directory is not included in the path. The command line tools will not work because of this commonly made mistake.

Note: Cygwin, AWS_AUTO_SCALING_HOME, EC2_PRIVATE_KEY, and EC2_CERT require using Linux/UNIX paths (For ex: /user/bin instead of C:\user\bin). However, JAVA_HOME requires a Windows path. Also, the value AWS_AUTO_SCALING_HOME should not contain any spaces, irrespective of whether the value is quoted, or spaces are escaped.

The following example shows us how to set the JAVA environment variable in Linux and UNIX. $ export JAVA_HOME=<PATH>

The following is an example of the Windows syntax: C:\> set JAVA_HOME=<PATH>

To confirm, you can run $JAVA_HOME/bin/java –version, and check the output:

$ $JAVA_HOME/bin/java -version
java version “1.5.0_09″
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)

The syntax, although different on Windows, has a similar output:

C:\> %JAVA_HOME%\bin\java -version
java version “1.5.0_09″
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)

Setting-Up the Tools

You are required to download the Auto-Scaling command tools, and set them up to the AWS account that you use. 

Getting the Command Line Tool

You can download the Auto Scaling Command Line Tools as a ZIP file. These tools have been written in Java, and include shell scripts for Windows 2000 and Windows XP, as well as Linux/UNIX and MAC OS. The ZIP file does not require any installation. You just have to unzip it once the download is complete. The following information tells you about additional setup required by the tools to successfully use your AWS account credentials.

Telling the Tools “Where they live”

Command line tools are dependent on an environment variable to successfully locate the supporting libraries. One needs to set this environment variable in order to use the command line tools. The variable has to be set to the path of the directory which contain the unzipped tools. This directory is named AutoScaling-ABCD (A, B, C, and D are release/version nos.), and contains the bin and lib sub directories.

The environment variable can be set on Linux/UNIX as follows: $ export AWS_AUTO_SCALING_HOME=<path-to-tools>

The syntax slightly differs for Windows: C:\> set AWS_AUTO_SCALING_HOME=<path-to-tools>

To make life easier, you can add the command line tools’ bin directory to the system PATH. The remaining guide assumes that this has been done.

The path can be updated on Linux/UNIX as follows: $ export PATH=$PATH:$AWS_AUTO_SCALING_HOME/bin

Again, the syntax differs for Windows: C:\> set PATH=%PATH%;%AWS_AUTO_SCALING_HOME%\bin

Note: Environment variables for Windows are reset once the command window is closed. They can be set permanently by using the setx command.

Telling the tools “Who you are”

One’s AWS credentials must be provided to the command line tools. You can either use your AWS access keys, or your AWS X.509 certificates.

Using Access Keys:

1. Visit the AWS security credentials website.
2. Retrieve your access key and its corresponding secret key. (For instructions on how to get these keys, please refer to the How to Get Your Access Key ID and Secret Access Key section.
3. Open the file $AWS_AUTO_SCALING_HOME/credential-file-path.template (%AWS_AUTO_SCALING_HOME%\credential-file-path.template on Windows) which has been downloaded as part of the tools’ ZIP file. The next step is to add your access and secret keys to the specific locations on the template file. You should save this file to a convenient location on the computer. A new name should be used for the file. On Linux, set the file permissions using the chmod 600 filename.
4. Use this file in either of the two following ways:

 (i)  Set the AWS_CREDENTIAL_FILE environment variable to the fully qualified path of the file that you created.

(ii) Specify the -aws-credential-file file name parameter with each command used.

You can also specify your access keys directly to the command line by including the --I [your access key] -S [your secret key] parameters.

Note: For most developers, creating a credential file and its corresponding AWS_CREDENTIAL_FILE environment variable is the easiest way of supplying your credentials to the command line tools

Using AWS X.509 Certificates:

1.  Log-in to the AWS security credentials website.
2. Click the X.509 Certificate button. Follow the given instructions to download the certificate and private key files to a secure location on your computer. Name these files appropriately (For ex: user-aws-cert.pem and user-aws-pk.pem).
3. These files can be used in either of the two following ways:

(i) You can specify the -ec2-cert-file-path= certificate file name and -ec2-private-key-file-path key file name parameters with every command used.

(ii) You can set the EC2_CERT environment variable to the fully qualified path of the certificate file created. Subsequently, you have to also set the EC2_PRIVATE_KEY environment variable to the fully qualified path of the key file that you created. This method saves the effort of specifying two parameters every time a command is used.

Changing the Region

By default, Auto-Scaling tools use the US East (Northern Virginia) Region, with the autoscaling.us-east-1.amazonaws.com service endpoint URL. To specify the Region for your Auto Scaling service, set AWS_AUTO_SCALING_REGION to the service endpoint URL. 

Specifying a Different Region:

1. Go to Regions and Endpoints.
2. The service endpoint can be changed by setting the AWS_AUTO_SCALING_URL environment variable as follows:

(i)  For Linux/UNIX: $ export AWS_AUTO_SCALING_URL=https://<service_endpoint>

(ii) For Windows:  C:\> set AWS_AUTO_SCALING_URL=https://<service_endpoint>

Note: By setting the EC2_REGION environment variable, the value you set using AWS_AUTO_SCALING_URL gets superseded.

Congratulations! You are ready to use Auto-Scaling now.