Memcached on AWS User Guide

Overview

This image runs Memcached, the open source high performance distributed memory caching system, fully installed and configured from the operating system's package repository. The Memcached service is enabled, starts on boot and listens on TCP 0.0.0.0:11211 with SASL PLAIN authentication required for every client. SASL plumbing, the libmemcached client tools (memcstat, memcexist, memctouch, memccat, memcrm, memcdump) and the python3-pylibmc client library are pre-installed.

On the first boot of every deployed instance a one shot service generates a fresh SASL password for the cloudimg user, writes it to the SASL credential database (/etc/sasl2/memcached-sasldb2), and records the password in a root only file at /root/memcached-credentials.txt. No shared or default credentials ship in the image.

A small nginx healthcheck shim serves a static OK response on TCP port 80 so AWS Marketplace scanners and external load balancers have an HTTP endpoint to probe. Memcached itself is TCP-only on 11211 and has no HTTP surface; the shim plays no operational role for customer traffic.

Memcached is volatile by design: the cache lives in RAM only and is lost on a Memcached restart or instance reboot. The default cache size on this image is 64 MiB; size it up for production via -m in /etc/memcached.conf and restart the service.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 11211 from your application tier's CIDR
• The AWS CLI version 2 installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Memcached. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger as a balanced default; size the instance to the working set you intend to cache. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 11211 from your application tier's CIDR. Do not open port 11211 to the public internet.

Select Launch instance. First boot initialisation takes only a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Memcached Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network and port 11211 from your application CIDR.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}' \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=memcached}]'

Step 3: Connect to the Instance over SSH

Connect to the instance with SSH as the default login user for the operating system variant you launched. The login user differs by variant:

Replace <key-file> with the path to your private key file and <instance-public-ip> with the public IP address or DNS name of the instance.

ssh -i <key-file> ubuntu@<instance-public-ip>

Step 4: Read the Per Instance Credentials

The per instance SASL password is stored in a root only file. Read it with sudo:

sudo cat /root/memcached-credentials.txt

The file contains the SASL MEMCACHED_USER (always cloudimg), the rotated MEMCACHED_PASSWORD, the listening port and address, and the instance's public IP. Keep this file private; it is the only place the rotated password is stored on the instance.

Step 5: Confirm Memcached Is Running

The cache server listens on TCP 11211 and the nginx healthcheck shim listens on TCP 80. Confirm both listeners with ss:

ss -tln | grep -E ':(11211|80) '

Confirm the systemd units are active and the Memcached version:

systemctl is-active memcached.service nginx.service
memcached --version

Probe the nginx healthcheck shim. It returns OK and HTTP 200; AWS Marketplace and external load balancers use this endpoint, not Memcached's own protocol.

curl -s http://127.0.0.1/

Step 6: Connect to the Cache with libmemcached-tools

The libmemcached-tools package provides the headless cache management CLI. Every command needs the --binary flag (SASL only works over the binary protocol) and the per instance username and password.

Run memcstat to print the server statistics — uptime, version, current connections, hit/miss counters and memory usage. Read the password from /root/memcached-credentials.txt and pass it on the same line:

PASS=$(sudo grep '^MEMCACHED_PASSWORD=' /root/memcached-credentials.txt | cut -d= -f2-) && memcstat --servers=127.0.0.1:11211 --binary --username='cloudimg' --password="${PASS}" | head -10

Check whether a key exists with memcexist. The command exits 0 when the key is present and non-zero otherwise — the example below probes a key that does not exist, so the command exits non-zero:

PASS=$(sudo grep '^MEMCACHED_PASSWORD=' /root/memcached-credentials.txt | cut -d= -f2-) && memcexist --servers=127.0.0.1:11211 --binary --username='cloudimg' --password="${PASS}" some-key; echo "memcexit_exit=$?"

Step 7: Round-trip SET / GET / DELETE from Python

The image ships the python3-pylibmc client library — SASL aware out of the box. Run a SET / GET / DELETE round-trip from a one-liner:

PASS=$(sudo grep '^MEMCACHED_PASSWORD=' /root/memcached-credentials.txt | cut -d= -f2-) && python3 -c "import pylibmc; c=pylibmc.Client(['127.0.0.1:11211'], binary=True, username='cloudimg', password='${PASS}'); c.set('greeting','hello cloudimg'); print('SET ok'); print('GET:', c.get('greeting')); c.delete('greeting'); print('DELETE ok')"

The same pylibmc.Client constructor works from any client host that can reach the instance on port 11211 — point ['<instance-private-ip>:11211'] at your VPC-internal address from application code.

Step 8: Sizing the Cache

The default cache size on this image is 64 MiB. Production workloads almost always need more. Edit /etc/memcached.conf and change the -m value to the megabytes of RAM you want Memcached to use:

sudo sed -i 's/^-m .*/-m 1024/' /etc/memcached.conf
sudo systemctl restart memcached.service

The setting above gives Memcached 1 GiB. Memcached pre-allocates slab pages on demand; raise -m toward (but not over) the instance's free RAM minus headroom for the kernel and any companion services. Confirm the new size by re-running memcstat and reading the limit_maxbytes line.

Step 9: Restrict Inbound Traffic to Your Application Tier

The build SG opens 11211 to the world for development convenience. Before exposing the cache to production traffic, edit the instance's security group and replace the 0.0.0.0/0 source on the 11211 rule with the CIDR of your application tier (e.g. the private subnet your web fleet runs in). SSH (22) and the nginx shim (80) follow the same principle: lock both down to your management CIDR before going live.

aws ec2 revoke-security-group-ingress \
  --group-id <security-group-id> \
  --protocol tcp --port 11211 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress \
  --group-id <security-group-id> \
  --protocol tcp --port 11211 --cidr <your-app-cidr>

Step 10: Rotate the SASL Password Manually

The per instance password is generated on first boot and not touched again. To rotate it manually, write a new password to the SASL database and update the credentials file. saslpasswd2 reads the new password from stdin with -p:

NEW=$(openssl rand -hex 16)
echo -n "${NEW}" | sudo saslpasswd2 -p -c -a memcached -f /etc/sasl2/memcached-sasldb2 cloudimg
sudo chown memcache:memcache /etc/sasl2/memcached-sasldb2
sudo chmod 0640 /etc/sasl2/memcached-sasldb2
sudo sed -i "s/^MEMCACHED_PASSWORD=.*/MEMCACHED_PASSWORD=${NEW}/" /root/memcached-credentials.txt
sudo systemctl restart memcached.service

The cache contents are flushed by the restart — that is normal for Memcached and acceptable for rotation in most cache designs because cache misses are non-fatal.

Step 11: Operational Tasks

Read the Memcached service journal to inspect live operations and any authentication events:

sudo journalctl -u memcached.service --no-pager -n 30

Flush the entire cache (drops every key, keeps the server running):

PASS=$(sudo grep '^MEMCACHED_PASSWORD=' /root/memcached-credentials.txt | cut -d= -f2-) && memcflush --servers=127.0.0.1:11211 --binary --username='cloudimg' --password="${PASS}"

Restart the cache (cache contents are wiped — Memcached is volatile):

sudo systemctl restart memcached.service

Step 12: Upgrade Memcached

Memcached on this image is installed from the Ubuntu package repository, so the standard apt upgrade flow applies. The package author bumps the version through normal Ubuntu security and stable updates.

sudo apt-get update
sudo apt-get install -y memcached
sudo systemctl restart memcached.service
memcached --version

The SASL configuration and the credentials file are untouched by the upgrade.

Screenshots

Support

For technical support, deployment assistance, or to report an issue with this image, contact cloudimg at support@cloudimg.co.uk. The support team is available 24/7 by email and chat and covers Memcached cache configuration, sizing, client integration, security review and upgrades.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.