How do I test my connection to an ElastiCache Redis OSS or Memcached cluster?

Resolution

Note: The following resolution tests a connection only for unplanned use. For a list of supported Redis clients, see Connect with Redis clients on the Redis website.

Amazon ElastiCache supports Redis OSS and Memcached in-memory key-value engines. When you launch an ElastiCache cache cluster, choose your preferred engine.

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

Create the ElastiCache cluster

To create an ElastiCache Redis OSS cluster, see Creating a cluster for Valkey or Redis OSS.

To create a Memcached cluster, see Creating a cluster for Memcached.

Connect to the ElastiCache Redis OSS cluster

ElastiCache supports both cluster mode disabled (CMD) and cluster mode enabled (CME) Redis OSS clusters. To test a connection to the clusters, use the redis-cli or redis6-cli utility. The latest version of redis-cli and redis6-cli supports SSL/TLS to connect to clusters with encryption or authentication turned on.

Download and compile the redis-cli utility on the Amazon Elastic Compute Cloud (Amazon EC2) instance that you want to connect from. For more information, see Get started with Amazon EC2.

Note: The following example uses Amazon EC2 instances that run Amazon Linux, Amazon Linux 2, and Amazon Linux 2023. To install and compile redis-cli and redis6-cli with other Linux distributions, see the documentation for your OS.

To connect to the ElastiCache Redis OSS cluster, run one of the following commands for your OS.

Amazon Linux 2023:

sudo yum install redis6 -y

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

When the Redis-cli connects to Redis, it uses an unencrypted TCP connection. When the redis-cli compiles, the BUILD_TLS=yes option turns on SSL/TLS. If the cluster that you connect to doesn't have encryption in transit, then you don't need the Build_TLS=yes option.

Note: When you install the redis6 package, you automatically install redis6-cli with default SSL/TLS support.

For information about how to find Redis endpoints, see Finding connection endpoints in ElastiCache.

In the following steps, encrypted or unencrypted clusters refer to the encryption in transit.

Connect to a CMD-unencrypted cluster

Note: In the following commands, replace change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com with the endpoint of your cluster and 6379 with your port number.

Run one of the following commands for your OS.

Amazon Linux 2023:

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

Amazon Linux and Amazon Linux 2:

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

The preceding command returns a Redis command prompt that's similar to the following example:

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

After you connect to the cluster, you can run Redis commands.

Example command:

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

For more information, see Commands on the Redis website.

Connect to a CME-unencrypted cluster

Note: In the following commands, replace cluster-disable-rediscli.54awdt.clustercfg.use1.cache.amazonaws.com with your cluster's configuration endpoint and 6379 with your port number.

Run one of the following commands for your OS.

Amazon Linux 2023:

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

Amazon Linux and Amazon Linux 2:

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

Note: In the preceding commands, option -c turns on cluster mode after -ASK and -MOVED redirections. If you don't turn on redirection, then the command returns the MOVED error. For more information, see Client and Server roles in the Redis cluster protocol and Redis cluster specification on the Redis website.

The preceding command returns a Redis command prompt that's similar to the following example:

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

Example Redis commands:

set x Hi-> Redirected to slot [16287] located at 172.31.28.122:6379OK
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"

Connect to a cluster with encryption or authentication turned on

To turn on AUTH you must also turn on in-transit encryption. For more information, see ElastiCache in-transit encryption (TLS).

To connect to both CME and cluster CMD-encrypted clusters, use the --tls option in the redis-cli. If a cluster has an AUTH token set, then use the option -a to provide an AUTH password.

Note: In Redis versions 7 and later, encryption in-transit is turned on for existing ElastiCache clusters. You don't need to rebuild or reprovision your cluster to change the TLS configuration for your Redis OSS cluster. And application availability isn't affected.

When you turn on in-transit encryption, update your client configuration to use the new TLS-specific endpoints.

Connect to CMD-encrypted clusters

Note: In the following commands, replace master.rediscli-cluster-disabled.54awdt.use1.cache.amazonaws.com with the configuration endpoint of your cluster and 6379 with your port number.

To connect to a CMD cluster with encryption and authentication turned on, run one of the following commands for your OS.

Amazon Linux 2023:

redis6-cli -h master.rediscli-cluster-disabled.54awdt.use1.cache.amazonaws.com --tls -a PASSWORD -p 6379

Amazon Linux and Amazon Linux 2:

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

To connect to a CMD cluster that has only encryption turned on, run one of the following commands for your OS:

Amazon Linux 2023:

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

Amazon Linux and Amazon Linux 2:

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

Connect to CME-encrypted clusters

To connect to a CME cluster with encryption and authentication turned on, run one of the following commands for your OS:

Amazon Linux 2023:

redis6-cli -h clustercfg.tlswithauth.54awdt.use1.cache.amazonaws.com --tls -c -a PASSWORD -p 6379

Amazon Linux and Amazon Linux 2:

src/redis-cli -h clustercfg.tlswithauth.54awdt.use1.cache.amazonaws.com --tls -c -a PASSWORD -p 6379

To connect to a CME cluster that has only encryption turned on, run one of the following commands for your OS:

Amazon Linux 2023:

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

Amazon Linux and Amazon Linux 2:

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

Redis-cli alternative

To run a short test without the redis-cli compilation, use telnet or openssl to connect to a CMD cluster.

After you connect, you can run Redis commands.

The following example command connects to an encrypted or authenticated CMD cluster:

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

If you set a password for the cluster, then connect to the cluster first. After you connect, run the following command to authenticate the cluster, and then press Enter:

Auth Password

Note: In the previous example command, replace Password with the password for your cluster

The following example command connects to a CMD cluster that doesn't have encryption or authentication turned on:

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

Connect to an ElastiCache Memcached cluster

To connect to a Memcached cluster, use the telnet utility.

Connect to a Memcached cluster without in-transit encryption

Complete the following steps:

1. Install the telnet utility on the instance that you want to test a connection from.

   For CentOS-based systems, run the following command:

   sudo yum install telnet

   For Debian-based systems (Ubuntu), run the following command:

   sudo apt-get install telnet

   To connect to an instance, see Connect to your EC2 instance.

2. To connect to the endpoint, run the following command:

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

   Note: Replace mycachecluster.eaogs8.0001.usw2.cache.amazonaws.com with your endpoint and 11211 with the port of your node.

   Example output:

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

   You're now connected to a node and you can run Memcached commands.

   Example Memcached commands:

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

Connect to a MemCached cluster with in-transit encryption

In-transit encryption is supported on clusters that run Memcached versions 1.6.12 and later. Telnet doesn't use encryption. To connect to an encryption-enabled MemCached cluster, use openssl.

Note: You can turn on in-transit encryption on a cluster only when you create the cluster. You can't modify the cluster to turn on or off in-transit encryption. For more information, see ElastiCache in-transit encryption (TLS).

To connect to the endpoint, run the following command:

openssl s_client -quiet -crlf -connect testwithtls.qtyxq7.cfg.apse2.cache.amazonaws.com:11211

Note: Replace testwithtls.qtyxq7.cfg.apse2.cache.amazonaws.com with your endpoint and 11211 with the port of your node.

Example output:

depth=2 C = US, O = Amazon, CN = Amazon Root CA 1  verify return:1  depth=1 C = US, O = Amazon, CN = Amazon RSA 2048 M02  
verify return:1  
depth=0 CN = *.testwithtls.qtyxq7.apse2.cache.amazonaws.com  
verify return:1

You're now connected to a node and you can run Memcached commands.

Example Memcached commands:

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