Reference - Amazon ElastiCache
Set up the Amazon CLI for ElastiCache
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Reference

The topics in this section cover working with the Amazon ElastiCache API and the ElastiCache section of the Amazon CLI. Also included in this section are common error messages and service notifications.

Setting up the ElastiCache command line interface

This section describes the prerequisites for running the command line tools, where to get the command line tools, how to set up the tools and their environment, and includes a series of common examples of tool usage.

Follow the instructions in this topic only if you are going to the Amazon CLI for ElastiCache.

Important

The Amazon ElastiCache Command Line Interface (CLI) does not support any ElastiCache improvements after API version 2014-09-30. To use newer ElastiCache functionality from the command line, use the Amazon Command Line Interface.

Prerequisites

This document assumes that you can work in a Linux/UNIX or Windows environment. The Amazon ElastiCache command line tools also work on Mac OS X, which is a UNIX-based environment; however, no specific Mac OS X instructions are included in this guide.

As a convention, all command line text is prefixed with a generic PROMPT> command line prompt. The actual command line prompt on your machine is likely to be different. We also use $ to indicate a Linux/UNIX specific command and C:\> for a Windows specific command. The example output resulting from the command is shown immediately thereafter without any prefix.

The Java runtime environment

The command line tools used in this guide require Java version 5 or later to run. Either a JRE or JDK installation is acceptable. To view and download JREs for a range of platforms, including Linux/UNIX and Windows, see Java SE Downloads.

Setting the Java home variable

The command line tools depend on an environment variable (JAVA_HOME) to locate the Java Runtime. This environment variable should be set to the full path of the directory that contains a subdirectory named bin which in turn contains the executable java (on Linux and UNIX) or java.exe (on Windows) executable.

To set the Java Home variable

  1. Set the Java Home variable.

    • On Linux and UNIX, enter the following command:

      $ export JAVA_HOME=<PATH>

    • On Windows, enter the following command:

      C:\> set JAVA_HOME=<PATH>

  2. Confirm the path setting by running $JAVA_HOME/bin/java -version and checking the output.

    • On Linux/UNIX, you will see output similar to the following:

      
$ $JAVA_HOME/bin/java -version
java version "1.6.0_23"
Java(TM) SE Runtime Environment (build 1.6.0_23-b05)
Java HotSpot(TM) Client VM (build 19.0-b09, mixed mode, sharing)

    • On Windows, you will see output similar to the following:

      
C:\> %JAVA_HOME%\bin\java -version
java version "1.6.0_23"
Java(TM) SE Runtime Environment (build 1.6.0_23-b05)
Java HotSpot(TM) Client VM (build 19.0-b09, mixed mode, sharing)

Getting the command line tools

The command line tools are available as a ZIP file on the ElastiCache Developer Tools web site. These tools are written in Java, and include shell scripts for Windows 2000/XP/Vista/Windows 7, Linux/UNIX, and Mac OSX. The ZIP file is self-contained and no installation is required; simply download the zip file and unzip it to a directory on your local machine.

Setting up the tools

The command line tools depend on an environment variable (Amazon_ELASTICACHE_HOME) to locate supporting libraries. You need to set this environment variable before you can use the tools. Set it to the path of the directory you unzipped the command line tools into. This directory is named ElastiCacheCli-A.B.nnnn (A, B and n are version/release numbers), and contains subdirectories named bin and lib.

To set the Amazon_ELASTICACHE_HOME environment variable

  • Open a command line window and enter one of the following commands to set the Amazon_ELASTICACHE_HOME environment variable.

    • On Linux and UNIX, enter the following command:

      $ export &AWS;_ELASTICACHE_HOME=<path-to-tools>

    • On Windows, enter the following command:

      C:\> set &AWS;_ELASTICACHE_HOME=<path-to-tools>

To make the tools easier to use, we recommend that you add the tools' BIN directory to your system PATH. The rest of this guide assumes that the BIN directory is in your system path.

To add the tools' BIN directory to your system path

  • Enter the following commands to add the tools' BIN directory to your system PATH.

    • On Linux and UNIX, enter the following command:

      $ export PATH=$PATH:$&AWS;_ELASTICACHE_HOME/bin

    • On Windows, enter the following command:

      C:\> set PATH=%PATH%;%&AWS;_ELASTICACHE_HOME%\bin
Note

The Windows environment variables are reset when you close the command window. You might want to set them permanently. Consult the documentation for your version of Windows for more information.

Note

Paths that contain a space must be wrapped in double quotes, for example:

"C:\Program Files\Java"

Providing credentials for the tools

The command line tools need the Amazon Access Key and Secret Access Key provided with your Amazon account. You can get them using the command line or from a credential file located on your local system.

The deployment includes a template file ${Amazon_ELASTICACHE_HOME}/credential-file-path.template that you need to edit with your information. Following are the contents of the template file:


AmazonAccessKeyId=<Write your Amazon access ID>
AmazonSecretKey=<Write your Amazon secret key>
Important

On UNIX, limit permissions to the owner of the credential file:

$ chmod 600 <the file created above>

With the credentials file setup, you'll need to set the Amazon_CREDENTIAL_FILE environment variable so that the ElastiCache tools can find your information.

To set the Amazon_CREDENTIAL_FILE environment variable

  1. Set the environment variable:

    • On Linux and UNIX, update the variable using the following command:

      $ export &AWS;_CREDENTIAL_FILE=<the file created above>

    • On Windows, set the variable using the following command:

      C:\> set &AWS;_CREDENTIAL_FILE=<the file created above>

  2. Check that your setup works properly, run the following command:

    elasticache --help

    You should see the usage page for all ElastiCache commands.

Environmental variables

Environment variables can be useful for scripting, configuring defaults or temporarily overriding them.

In addition to the Amazon_CREDENTIAL_FILE environment variable, most API tools included with the ElastiCache Command Line Interface support the following variables:

  • EC2_REGION — The Amazon region to use.

  • Amazon_ELASTICACHE_URL — The URL to use for the service call. Not required to specify a different regional endpoint if EC2_REGION is specified or the --region parameter is passed.

The following examples show how to set the environmental variable EC2_REGION to configure the region used by the API tools:

Linux, OS X, or Unix


$ export EC2_REGION=us-west-1

Windows


$ set EC2_REGION=us-west-1