How do I test my connection to an Amazon ElastiCache Redis or Memcached Cluster?

Last updated: 2021-02-10

How can I test my connection to an Amazon ElastiCache for Redis or Amazon ElastiCache for Memcached cluster using a client such as redis-cli or telnet from a Linux-based client?

Short description

Amazon ElastiCache currently supports two different in-memory key-value engines, Redis and Memcached. You can choose the engine you prefer when launching an ElastiCache cache cluster.

Note: This resolution covers testing a connection only for unplanned use. For a list of supported Redis clients, see the Redis documentation.

For Memcached with Java, .NET, or PHP, it's a best practice to use ElastiCache clients with Auto Discovery. ElastiCache clients with Auto Discovery support Auto Discovery of new ElastiCache nodes as they're added to the cache cluster.

Resolution

Connecting to the Redis cluster

ElastiCache supports both cluster mode disabled and cluster mode enabled Redis clusters. To test a connection to these clusters, you can use the redis-cli utility. The latest version of redis-cli also supports SSL/TLS for connecting Encryption/Authentication enabled clusters.

Download and compile redis-cli utility on the Amazon Elastic Compute Cloud (Amazon EC2) instance that you're making a connection from. For instructions on how to connect to an Amazon EC2 instance, see Tutorial: Get started with Amazon EC2 Linux instances.

Note: The following example uses EC2 instances running Amazon Linux and Amazon Linux 2. For documentation on installing and compiling redis-cli with other Linux distributions, see the documentation for your specific operating system.

Amazon Linux 2

$sudo amazon-linux-extras install epel -y
$sudo yum install gcc jemalloc-devel openssl-devel tcl tcl-devel -y
$sudo wget http://download.redis.io/redis-stable.tar.gz
$sudo tar xvzf redis-stable.tar.gz
$cd redis-stable
$sudo make BUILD_TLS=yes

Amazon Linux

$sudo yum install gcc jemalloc-devel openssl-devel tcl tcl-devel clang wget
$sudo wget http://download.redis.io/redis-stable.tar.gz
$sudo tar xvzf redis-stable.tar.gz
$cd redis-stable
$sudo CC=clang make BUILD_TLS=yes

Note: If the cluster you're connecting to isn't encrypted, you don't need the Build_TLS=yes option.

For information on finding Redis endpoints, see Finding connection endpoints.

Connecting to a cluster mode disabled unencrypted cluster

1.    Run the following command to connect to the cluster. In the following example command, replace 54awdt.ng.0001.use1.cache.amazonaws.com and 6379 endpoint of your cluster and your port number.

src/redis-cli -h change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com -p 6379

The following is an example of the Redis command prompt returned by the preceding command:

change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com:6379>

2.    Run Redis commands.

After you connect to the cluster, you can run Redis commands. The following are example Redis commands:

set a "hello"
OK
get a
"hello"
quit

Connecting to a cluster mode enabled unencrypted cluster

1.    Run the following command to connect to the cluster. In the following example command, replace 54awdt.ng.0001.use1.cache.amazonaws.com and 6379 with the endpoint of your cluster and your port number.

src/redis-cli -h cluster-disabled-rediscli.54awdt.clustercfg.use1.cache.amazonaws.com -c -p 6379

Note: In the preceding command, option -c enables cluster mode following -ASK and -MOVED redirections.

The result in a Redis command prompt looks similar to the following:

cluster-disabled-rediscli.54awdt.clustercfg.use1.cache.amazonaws.com:6379>

2.    You can now run Redis commands. Note that redirection occurs because you enabled it using the -c option. If redirection isn't enabled, the command returns the MOVED error. For more information on the MOVED error, see Redis cluster specification on the redis.io website.

set x Hi
-> Redirected to slot [16287] located at 172.31.28.122:6379
OK
set y Hello
OK
get y
"Hello"
set z Bye
-> Redirected to slot [8157] located at 172.31.9.201:6379
OK
get z
"Bye"
get x
-> Redirected to slot [16287] located at 172.31.28.122:6379
"Hi"

Connecting to an Encryption/Authentication enabled cluster

By default, redis-cli uses an unencrypted TCP connection when connecting to Redis. The option BUILD_TLS=yes enables SSL/TLS at the time of redis-cli compilation as shown in the preceding Connecting to a Redis cluster section. Enabling AUTH is optional. However, you must enable encryption in-transit in order to enable AUTH. For more details on ElastiCache encryption and authentication, see ElastiCache for Redis in-transit encryption (TLS).

Note: You can use the option --tls with redis-cli to connect to both cluster mode enabled and disabled encrypted clusters. If a cluster has an AUTH token set, then you can use the option -a to provide an AUTH password.

In the following examples, make sure to substitute the endpoint and port of your cluster.

Connect to cluster mode disabled encrypted clusters

The following example connects to an encryption and authentication enabled cluster:

src/redis-cli -h master.rediscli-cluster-disabled.54awdt.use1.cache.amazonaws.com --tls -a <Password> -p 6379

The following example connects to a cluster that has only encryption enabled:

src/redis-cli -h master.cluster-disabled-noauth.54awdt.use1.cache.amazonaws.com --tls -p 6379

Connect to cluster mode enabled encrypted clusters

The following example connects to an encryption and authentication enabled encrypted cluster:

src/redis-cli -h master.rediscli-cluster-disabled.54awdt.use1.cache.amazonaws.com --tls -c -a <Password> -p 6379

The following example connects to a cluster that has only encryption enabled:

redis-cli -h clustercfg.tlswithoutauth.54awdt.use1.cache.amazonaws.com --tls -c -p 6379

After you connect to the cluster, you can run the Redis commands as shown in the preceding examples for unencrypted clusters.

Redis-cli alternative

If the cluster isn't cluster mode enabled and you need to make a connection to the cluster for a short test but without going through the redis-cli compilation, you can use telnet or openssl. In the following example commands, make sure to substitute the endpoint and port of your cluster as necessary.

After you connect, you can run Redis commands as shown in the preceding examples.

The following example connects to an encryption and/or authentication cluster mode disabled cluster:

openssl s_client -connect master.rediscli-cluster-disabled.54awdt.use1.cache.amazonaws.com:6379

If the cluster has a password set, first connect to the cluster. After connecting, authenticate the cluster using the following command, then press the Enter key. In the following example, replace Password with the password for your cluster.

Auth Password

The following example connects to a cluster mode disabled cluster that doesn't have encryption or authentication enabled:

telnet change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com 6379

Connecting to a MemCached cluster

To connect to a MemCached cluster, use the telnet utility. For more information about Memcached and available Memcached commands, see the Memcached website. For details on finding Memcached endpoints, see Finding connection endpoints.

1.    Install the telnet utility on the EC2 instance that you're testing a connection from.

CentOS-based systems:

$sudo yum install telnet

Debian-based systems (Ubuntu):

$sudo apt-get install telnet

For instructions on how to connect to an Amazon EC2 instance, see Tutorial: Get started with Amazon EC2 Linux instances.

2.    Use the following command to connect to the endpoint. Replace eaogs8.0001.usw2.cache.amazonaws.com with your endpoint and 11211 with the port of your node.

telnet mycachecluster.eaogs8.0001.usw2.cache.amazonaws.com 11211

The output looks similar to the following:

Trying 128.0.0.1...
Connected to mycachecluster.eaogs8.0001.usw2.cache.amazonaws.com.
Escape character is '^]'.
>

You're now connected to a node. You can run Memcached commands as shown in the following examples:

set a 0 0 5
hello
STORED
get a
VALUE a 0 5
hello
END

Did this article help?


Do you need billing or technical support?