Amazon CloudSearch
Developer Guide (API Version 2013-01-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Using the Command Line Tools for Amazon CloudSearch

This section describes how to install and run the standalone Amazon CloudSearch command line tools. For information about installing and using the AWS CLI, see the AWS Command Line Interface User Guide.

Prerequisites for Installing the Amazon CloudSearch Command Line Tools

To use the Amazon CloudSearch command line tools, you need:

  • A basic familiarity with working in a Linux/UNIX or Windows environment.

  • A Java 7-compatible Java Runtime Environment (JRE). You can download the latest JRE from java.com.

  • A JAVA_HOME environment variable that points to your Java runtime. This environment variable should be set to the full path of the directory that contains the bin directory that contains the java (Linux/UNIX) or java.exe (Windows) executable.

  • An AWS access key ID and secret access key. Use IAM user access keys instead of AWS root account access keys. IAM lets you securely control access to AWS services and resources in your AWS account. For more information about getting credentials, see How Do I Get Security Credentials? in the AWS General Reference.

Installing the Command Line Tools for Amazon CloudSearch

To install the Amazon CloudSearch command line tools

  1. To download the command line tools for Windows, go to https://aws.amazon.com/developertools/4320728073503020 and click the Download button.

  2. To download the command line tools for Mac OS/Linux, go to https://aws.amazon.com/developertools/9054800585729911 and click the Download button.

  3. Unpack the .zip or .tar.gz file. On Windows, we recommend unzipping the tools in the C:\CloudSearch directory.

  4. Set the CS_HOME environment variable to point to the directory where you unpacked the tools.

    On Linux and UNIX, enter following command:

    export CS_HOME=install_directory_path

    On Windows, enter the following command:

    set CS_HOME=install_directory_path

    Note

    These examples temporarily set the CS_HOME and PATH variables for the duration of your terminal session. You can also set them permanently. On Linux and MacOSX, add the export commands to your shell startup file (.profile, .bashrc, .tcshrc, or .zshrc) in your home directory. On Windows, you can do this through the Control Panel: Control Panel > System and Security > System > Advanced > Environment Variables.

  5. Add the CS_HOME environment variable to your PATH.

    On Linux and UNIX, enter following command:

    export PATH=$PATH:$CS_HOME/bin

    On Windows, enter the following command:

    set PATH=%PATH%;%CS_HOME%\bin 
  6. Make sure you have the Java 7 (or later) JRE installed and that the JAVA_HOME environment variable is set to the full path of the directory that contains the bin directory in which the Java executable resides. For information about checking your Java installation, go to java.com.

    Note

    On Mac OS X, JAVA_HOME should be set using the /usr/libexec/java_home command. For example: export JAVA_HOME=$(/usr/libexec/java_home). For more information, see QA1170 on developer.apple.com.

  7. Configure the command line tools to use your AWS identifiers. The Amazon CloudSearch command line tools look for your AWS identifiers in a text file on your local system in the location specified by the AWS_CREDENTIAL_FILE environment variable. If you have not already configured an AWS credential file, follow these steps:

    1. Use a text editor to create a two-line text file that specifies your AWS identifiers. The first line sets the accessKey property and the second line sets the secretKey property, as shown in this example:

      accessKey=AKIAIOSFODNN7EXAMPLE
      secretKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    2. Save the file using any name you want (for example, account-key).

    3. Limit the file permissions to only the file owner. (For example, use chmod 600 on the file if you are using Linux/UNIX).

    4. Set the AWS_CREDENTIAL_FILE environment variable.

      On Linux and UNIX, enter following command:

      export AWS_CREDENTIAL_FILE=credential_file_path

      On Windows, enter the following command:

      set AWS_CREDENTIAL_FILE=credential_file_path
  8. Set the CS_ENDPOINT environment variable to specify the Amazon CloudSearch configuration service endpoint for the AWS region where you want to create and configure search domains. See Amazon CloudSearch Regions and Endpoints for a list of supported regions.

    On Linux and UNIX, enter following command:

    export CS_ENDPOINT=cloudsearch.region.amazonaws.com

    On Windows, enter the following command:

    set CS_ENDPOINT=cloudsearch.region.amazonaws.com

    Note

    If CS_ENDPOINT is not set, the Amazon CloudSearch command line tools default to the configuration service endpoint in the US East (Northern Virginia) Region, cloudsearch.us-east-1.amazonaws.com. You can also explicitly set the endpoint by specifying the --endpoint option when you run Amazon CloudSearch commands.

  9. To verify that the Amazon CloudSearch tools are configured correctly, run the cs-describe-domain command. (Because you haven’t configured any domains yet, the Domain Summary is empty.)

    cs-describe-domain

    If you get an error, check the following:

    • If the system cannot find the specified path, your need to set your JAVA_HOME environment variable to the location where the JRE is installed, such as C:\Program Files\Java\jre6.

    • If cs-describe-domain is not recognized as a command, make sure your PATH contains the bin directory for the command line tools, such as /Users/username/CloudSearch/tools/bin.

    • If you get an InvalidClientTokenId error, your AWS credentials are not configured correctly. Make sure that you’ve configured the AWS_CREDENTIAL_FILE environment variable and that your credential file contains a valid AWS access key ID and secret access key.

Running the Amazon CloudSearch Commands

All of the Amazon CloudSearch commands require an AWS access key ID and secret access key. The easiest way to specify your keys is to set up an AWS credential file and set the AWS_CREDENTIAL_FILE environment variable as described in the installation instructions.

You can also explicitly specify your keys with each request, either by using the --aws-credential-file option to specify the location of your credential file, or by specifying both the --access-key and --secret-key options.

You must also specify the name of your search domain with the -d or --domain-name option.