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

9 minute read
1

I want to test my connection to an Amazon ElastiCache for Redis or Amazon ElastiCache for Memcached cluster from a Linux-based client.

Short description

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

Note: This resolution covers testing a connection only for unplanned use. For a list of supported Redis clients, see the Redis website 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 automatically identify new ElastiCache nodes when they're added to the cache cluster.

Resolution

Create the ElastiCache cluster

Note: If you're connecting to an existing cluster, then proceed to the next step.

For information on how to create an ElastiCache Redis cluster, see Create a cluster (Amazon ElastiCache for Redis User Guide).

For information on how to create a Memcached cluster, see Create a cluster (Amazon ElastiCache for Memcached User Guide).

Connect to the ElastiCache Redis cluster

ElastiCache supports both cluster mode disabled and cluster mode enabled Redis clusters. To test a connection to these 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 and authentication turned on. Download and compile the redis-cli utility on the Amazon Elastic Compute Cloud (Amazon EC2) instance that you're connecting 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 that run Amazon Linux, Amazon Linux 2, and Amazon Linux 2023. For documentation on installing and compiling redis-cli and redis6-cli with other Linux distributions, see the documentation for your specific operating system.

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

By default, redis-cli uses an unencrypted TCP connection when it connects to Redis. When 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. In the following steps, encrypted or unencrypted clusters refer to encryption in transit.

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

For information on how to find Redis endpoints, see Finding connection endpoints.

Connect to a cluster mode disabled unencrypted cluster

  1. To connect to the cluster, run the following command. In the following example command, replace change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com and 6379 with the endpoint of your cluster and your port number:

    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

    This command returns a Redis command prompt that looks similar to the following example:

    change-node-type.54awdt.ng.0001.use1.cache.amazonaws.com:6379>
  2. After you connect to the cluster, you can run Redis commands such as the following examples:

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

    For more information, see Commands on the redis.io website.

Connect to a cluster mode enabled unencrypted cluster

To connect to the cluster, run the following command. In the following example command, replace cluster-disable-rediscli.54awdt.clustercfg.use1.cache.amazonaws.com and 6379 with the configuration endpoint of your cluster and your port number:

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 these commands, option -c turns on cluster mode after -ASK and -MOVED redirections. For more information, see Client and Server roles in the Redis cluster protocol on the redis.io website.

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

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

You can now run Redis commands. Redirection occurs because of the -c option. If you don't turn on redirection, then the command returns the MOVED error. For more information on the MOVED error, see Redis cluster specification on the Redis website.

Here are some example Redis commands:

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"

Connect to a cluster with encryption and authentication turned on

You have the option to turn on AUTH. However, to turn on AUTH, you must turn on in-transit encryption. For details on ElastiCache encryption and authentication, see ElastiCache in-transit encryption (TLS).

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

Note: In Redis version 7 and later, encryption in-transit is turned on for existing ElastiCache clusters. You can change your Redis clusters' TLS configuration without re-building or re-provisioning them or impacting application availability. When you turn on in-transit encryption, update your client configuration to use the new TLS-specific endpoints. For more information, see Best practices to establish connections before, during, and after enabling in-transit encryption.

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

Connect to cluster mode disabled encrypted clusters

The following example command connects to a cluster with encryption and authentication turned on:

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

The following example command connects to a cluster that has only encryption turned on:

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 cluster mode enabled encrypted clusters

The following example command connects to a cluster with encryption and authentication turned on:

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

The following example command connects to a cluster that has only encryption turned on:

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

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

Redis-cli alternative

For a short test without going through the redis-cli compilation, you can connect to a cluster that isn't cluster mode enabled. To do this, use telnet or openssl. In the following example commands, substitute the endpoint and port of your cluster.

Note: To install the telnet utility, see the following section Connect to a Memcached cluster without in-transit encryption.

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

The following example command connects to an encryption 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, then connect to the cluster first. After you connect, use the following command to authenticate the cluster, and then use the Enter key. In the following example command, replace Password with the password for your cluster:

Auth Password

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

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

Connecting to an ElastiCache Memcached cluster

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

Connect to a Memcached cluster without in-transit encryption

  1. Install the telnet utility on the EC2 instance that you're testing 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

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

  2. To connect to the endpoint, run the following example command. Replace mycachecluster.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 example:

    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 example output:

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

Connecting 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 the openssl client.

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

To connect to the endpoint, run the following example command. Replace testwithtls.qtyxq7.cfg.apse2.cache.amazonaws.com with your endpoint and 11211 with the port of your node:

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

Here's an 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. You can run Memcached commands as shown in the following example output:

set a 0 0 5hello
STORED
get a
VALUE a 0 5
hello
END
AWS OFFICIAL
AWS OFFICIALUpdated 6 months ago
4 Comments

If you inheret admin of a redis cluster, how do you tell if there is a password or not? Also how to recover what the password is?

gwhiz
replied a year ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied a year ago

If a cluster is just encrypted at-rest (not yet in-transit encrypted) does it refer to an encrypted or unencrypted cluster in this doc? Also, I found it confusing at "Connecting to a cluster mode enabled unencrypted cluster" that the commands uses cluster-disable* endpoints when title is cluster-enabled. Users should understand the case where cluster-enabled, at-rest encrypted (should be clarified whether considered encrypted or not in this doc) need to adjust their endpoint.

Here is an example which is not addressed - when the target is to enable in-transit encryption for cluster-enabled, at-rest encrypted cluster, the endpoint should also change - From: cluster-name.54awdt.clustercfg.use1.cache.amazonaws.com To: clustercfg.cluster-name.54awdt.use1.cache.amazonaws.com Note: 'clustercfg' in the endpoint name moved from the 3rd field to 1st field.

Maybe table/s with all endpoint naming changes according to the from/to states can be beneficial

replied 7 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
MODERATOR
replied 7 months ago