Skip to content

How to install the CLI Amazon tools on a Mac

Posted in System, and Tutorials

2019 update, there now is a guide to install the AWS CLI tools on Mac. It’s probably been there for a while but still after I published this.

Recently I had to connect to an amazon EC2 instance using SSH to do some stuff and realized that there is no manual for the Mac setup, but for Unix-like OS. However, since OS X is Unix based the instructions kinda work but if you’re unaware of some specifics you may get stuck at some point, plus even googling did not help me there. As I managed to make it quite easily, I thought it is my duty to share it with the world. That somewhere on the internet there is a reference allowing you to just copy-paste commands to gain time. Yes, the good engineer is lazy (work for devs too). Not the lazy laziness of not doing anything, but the one that forces you to think something long and well enough so you don’t have to restart it or to do it again and again.

Note

This guide is partially inspired from Amazon’s documentation on the subject

A. Download and Install the CLI Tools

First of all you will need the Amazon CLI tools. Download the tools. The CLI tools are available as a .zip file on this site: Amazon EC2 CLI Tools (aws.amazon.com/developertools/351). You can also download them with the curl utility.

curl http://s3.amazonaws.com/ec2-downloads/ec2-api-tools.zip -o ec2-api-tools.zip

You can, optionnal, verify that the CLI tools package has not been altered or corrupted after publication. For more information about authenticating the download before unzipping the file, see Verify the Signature of the Tools Download.

Unzip the files into a suitable installation directory, such as /usr/local/ec2. Notice that the .zip file contains a folder ec2-api-tools-x.x.x.x, where x.x.x.x is the version number of the tools (for example, ec2-api-tools-1.6.12.2).

sudo mkdir /usr/local/ec2
sudo unzip ec2-api-tools.zip -d /usr/local/ec2

B. Tell the Tools Where Java Lives

You can verify whether you have Java installed and where it is located using the following command:

which java

You should see the following is example output.

/usr/bin/java

If the previous command does not return a location for the Java binary, you need to install Java. For help installing Java on your platform, go here.

Find the Java home directory on your system. The which java command executed earlier returns Java’s location in the $PATH environment variable, but in most cases this is a symbolic link to the actual program; symbolic links do not work for the JAVA_HOME environment variable, so you need to locate the actual binary. The /usr/libexec/java_home command returns a path suitable for setting the JAVA_HOME variable.

/usr/libexec/java_home

Set JAVA_HOME to the full path of the Java home directory. Set the JAVA_HOME variable to $(/usr/libexec/java_home). The following command sets this variable to the output of the java_home command; the benefit of setting the variable this way is that it updates to the correct value if you change the location of your Java installation later.

export JAVA_HOME=$(/usr/libexec/java_home)

You can verify your JAVA_HOME setting using this command.

$JAVA_HOME/bin/java -version

If you’ve set the environment variable correctly, the output looks something like this.

java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

Add this environment variable definition ($JAVA_HOME) to your shell start up scripts so that it is set every time you log in or spawn a new shell. The name of this startup file differs across platforms (in Mac OS X, this file is commonly called ~/.bash_profile and in Linux, it is commonly called ~/.profile), but you can find it with the following command:

ls -al ~ | grep profile

If the file does not exist, you can create it. Use your favorite text editor to open the file that is listed by the previous command, or to create a new file with that name. Then edit it to add the variable definition you set in Step 3.

If the file exist set rights so you can edit it, then edit it using textedit, and change permissions again

sudo chmod 777 ~/.profile
sudo open -a TextEdit ~/.profile
sudo chmod 400 ~/.profile

Verify that the variable is set properly for new shells by opening a new terminal window and testing that the variable is set with the following command.

Note: If the following command does not correctly display the Java version, try logging out, logging back in again, and then retrying the command.

$JAVA_HOME/bin/java -version

C. Tell the CLI Tools Where They Live

The Amazon EC2 CLI tools read the EC2_HOME environment variable to locate supporting libraries. Before using these tools, set EC2_HOME to the directory path where you unzipped them. This directory is named ec2-api-tools-w.x.y.z (where w, x, y, and z are components of the version number). It contains sub-directories named bin and lib.

In addition, to make things a little easier, you can add the bin directory for the CLI tools to your system path. The examples in the Amazon Elastic Compute Cloud User Guide assume that you have done so.

You can set the EC2_HOME and PATH environment variables as follows. Add them to your shell start up scripts so that they’re set every time you log in or spawn a new shell.

To set the EC2_HOME and PATH environment variables on Linux/Unix

Use this command to set the EC2_HOME environment variable. For example, if you unzipped the tools into the /usr/local/ec2 directory created earlier, execute the following command, substituting the correct version number of the tools.

export EC2_HOME=/usr/local/ec2/ec2-api-tools-1.6.12.2

Note

If you are using Cygwin, EC2_HOME must use Linux/Unix paths (for example, /usr/bin instead of C:\usr\bin). Additionally, the value of EC2_HOME cannot contain any spaces, even if the value is quoted or the spaces are escaped.

You can update your PATH as follows.

export PATH=$PATH:$EC2_HOME/bin

D. Tell the CLI Tools Who You Are

Your access keys identify you to the Amazon EC2 CLI tools. There are two types of access keys: access key IDs and secret access keys. You should have stored your access keys in a safe place when you created them. Although you can retrieve your access key ID from the Your Security Credentials page, you can’t retrieve your secret access key. Therefore, if you can’t find your secret access key, you’ll need to create new access keys before you can use the CLI tools.

Every time you issue a command, you must specify your access keys using the –aws-access-key and –aws-secret-key (or -O and -W) options. Alternatively, you might find it easier to store your access keys using the following environment variables:

AWS_ACCESS_KEY—Your access key ID
AWS_SECRET_KEY—Your secret access key

If these environment variables are set properly, their values serve as the default values for these required options, so you can omit them from the commands. You can add them to your shell startup scripts so that they’re set every time you log in or spawn a new shell.

You can set these environment variables as follows.

export AWS_ACCESS_KEY=your-aws-access-key-id
export AWS_SECRET_KEY=your-aws-secret-key

E. (Optional) Set the Region

By default, the Amazon EC2 CLI tools use the US East (Northern Virginia) region (us-east-1) with the ec2.us-east-1.amazonaws.com service endpoint URL. To access a different region with the CLI tools, you must set the EC2_URL environment variable to the proper service endpoint URL.

To set the service endpoint URL

To list your available service endpoint URLs, call the ec2-describe-regions command, as shown in the previous section.

Set the EC2_URL environment variable using the service endpoint URL returned from the ec2-describe-regions command as follows.

export EC2_URL=https://<service_endpoint>

If you’ve already launched an instance using the console and wish to work with the instance using the CLI, you must specify the endpoint URL for the instance’s region. You can verify the region for the instance by checking the region selector in the console navigation bar.

For more information about the regions and endpoints for Amazon EC2, see Regions and Endpoints in the Amazon Web Services General Reference.

Be First to Comment

    Leave a Reply

    This site uses Akismet to reduce spam. Learn how your comment data is processed.

    %d bloggers like this: