What this module does #

Memcached is configured with a text file and a handful of flags: how much RAM to give it, how many threads, how many connections. Getting those numbers right depends on the instance size, and getting them wrong is expensive — either you run short of cache or you eat the RAM the system needs.

The memcached module takes care of that and of everything around the service: it works out the tuning from the machine's real RAM, manages the SASL credentials (mandatory in this image), maintains the TLS certificate generated on first boot —never baked into the AMI— and gives you the live status with the service statistics.

Before you start

Commands that read credentials or touch the configuration need root (use sudo). Careful with optimize: applying new values restarts the service, and a restart empties the cache. If you would rather apply now and restart yourself, use --no-restart.

Quick guidestep-by-step tasks

Quick guide #

Pick what you want to do. Every recipe comes with the command already written — just copy it and hit Copy.

Check the service status Connect to the cache Tune the cache size Create SASL users Review the TLS certificate

1

Check the service status

Check at a glance that the cache is healthy and what tuning is applied.

Connect to your instance over SSH with the ubuntu user.

Ask for the status: you will see which ports it listens on, whether TLS and SASL are on, the applied tuning and live statistics (memory in use, items, hits and misses):

terminal

$ sudo imaxe memcached status

Want it for a dashboard or a script? Add --json:

terminal

$ sudo imaxe memcached status --json

If hits keeps growing and evictions stays low, the cache is well sized. If evictions spike, jump to Tune the cache size.

2

Connect to the cache

Get the user, password and port to point your application at.

This image requires SASL: there is no anonymous access. Ask for this instance's credentials (the password comes out masked):

terminal

$ sudo imaxe memcached credentials

When you actually need to copy it, print it in the clear:

terminal

$ sudo imaxe memcached credentials --show-password

Port 11211 speaks TLS; 11212 is plaintext and only listens on loopback, for the system's own tools. Do not open 11211 to the Internet: open it to your VPC CIDR.

3

Tune the cache size

Recompute memory, threads and connections for the machine's real size.

First see what the values would be, without touching anything:

terminal

$ sudo imaxe memcached optimize --show

If they convince you, apply them. The service restarts and the cache is emptied:

terminal

$ sudo imaxe memcached optimize

Want more cache and less headroom for the system? Raise the RAM percentage:

terminal

$ sudo imaxe memcached optimize --memory-pct 75

With --dry-run you also see the configuration block that would be written. And with --no-restart it applies without restarting: the new values take effect on the next boot.

4

Create SASL users

Create, rotate or delete the credentials your applications use.

List the users that exist in the SASL database:

terminal

$ sudo imaxe memcached users list

Create one per application, with a random password:

terminal

$ sudo imaxe memcached users add app1

Need a specific password? Pass it on standard input so it does not end up in ps or your shell history:

terminal

$ sudo imaxe memcached users add app1 --stdin

To change a user's password, imaxe memcached users rotate <user>. With no name it rotates the product user's.

5

Review the TLS certificate

Check the expiry date and renew the instance certificate.

The certificate is generated on each instance's first boot, so it is never shared between machines. Look at the one in use:

terminal

$ sudo imaxe memcached tls show

Renew it whenever you like, even if the current one is still valid:

terminal

$ sudo imaxe memcached tls renew --force

It is a self-signed certificate with a long validity. Your client will have to trust it or check its SHA-256 fingerprint, which is what tls show prints.

Not starting, or the credential is missing?

The credential and the certificate are materialised by instance-setup on every boot, called by systemd. If a command answers with code 65, that instance has not completed its first boot: check sudo systemctl status memcached before touching anything.

CLI referencecommands, flags and files

Synopsis #

usage

imaxe memcached <subcommand> [flags]

Almost every subcommand needs root (use sudo) because it reads the SASL database, the certificate or the service configuration. Add --json to status, credentials, users list or tls show for machine-readable output.

Subcommands #

Subcommand	What it does	Relevant flags
optimize	Works out and applies the best cache size, threads and connections for this instance.	--memory-pct --dry-run --show --no-restart
status	Service status: listeners, TLS, SASL, applied tuning and live statistics.	--json
credentials	Shows this instance's SASL credentials and how to connect.	--json --show-password
users	Manages SASL users: `list`, `add`, `rotate` and `delete`.	--password --stdin --json
set-password	Changes the product's SASL user password. Shortcut for `users rotate`.	--random --stdin
open-port	Opens the memcached port on the host firewall (ufw).	--cidr --json
close-port	Closes the port on the host firewall and removes any rules it finds.	--json
tls	This instance's TLS certificate: `show` and `renew`.	--force --json
instance-setup	Prepares the instance before the service starts. systemd calls it on every boot.	--bake

Arguments and flags #

Flag	Type	Default	Description
--memory-pct	int	60	In `optimize`: percentage of usable RAM devoted to the cache.
--reserve-mem-mb	int	512	In `optimize`: RAM in MB that is left alone, reserved for the OS and other services.
--threads	int	0	In `optimize`: worker threads. `0` derives them from the CPU count.
--max-connections	int	0	In `optimize`: simultaneous connections. `0` derives them from the cache size.
--dry-run	bool	false	In `optimize`: writes nothing; shows the values and the configuration block that would be applied.
--show	bool	false	In `optimize`: only prints the computed values.
--no-restart	bool	false	In `optimize`: writes the configuration but does not restart the service. A restart empties the cache.
--password	string	—	In `users add`/`rotate`: a specific password. If omitted, a random one is generated.
--stdin	bool	false	In `users add`/`rotate`: reads the password from standard input, so it does not show up in `ps` or the history.
--show-password	bool	false	In `credentials`: prints the password in the clear. Masked by default.
--force	bool	false	In `tls renew`: regenerates even if the current certificate is valid and belongs to this instance.
--random	bool	false	In `set-password`: generates a strong password and prints it once.
--cidr	string	—	In `open-port`: restricts the rule to that source. Without it, any source is allowed.
--json	bool	false	Emits the result as structured JSON on `stdout`.

Files and paths #

Path	Contents
/etc/imaxe/memcached.yml	Module configuration: service, paths, and the defaults for `optimize`, TLS and SASL.
/etc/memcached.conf	memcached configuration. Written by `optimize`: do not edit it by hand.
/etc/systemd/system/memcached.service.d/	systemd drop-in with the startup parameters the module applies.
/etc/memcached/tls/	Certificate and private key for this instance, generated on first boot.
/etc/sasl2/memcached-sasldb2	SASL database with the users and their passwords.

Example memcached.yml:

/etc/imaxe/memcached.yml

service: memcached
port: 11211
optimize:
  memory_pct: 60
  memory_min_mb: 64
  reserve_mem_mb: 512
  threads: 0
  max_connections: 0
tls:
  enabled: true
  days: 3650
  plain_local_port: 11212
sasl:
  enabled: true
  user: memcached

Exit codes and logs #

Every run returns a code you can check with echo $? — handy for chaining in scripts:

0OKOperation completed successfully.

1ERRUnclassified generic error. Check the log.

2USAGEInvalid arguments or subcommand.

64NOMEMCACHEDmemcached is not installed on this machine.

65NOSECRETA credential was requested that this instance has not generated yet.

66NOUFWufw is not available on this machine.

Follow the service live while you work:

terminal

$ sudo systemctl status memcached
$ sudo journalctl -u memcached -f

Troubleshooting #

Symptom	Likely cause	Fix
You get NOSECRET (code 65)	The instance has not completed its first boot, which is when the credential is materialised.	Check `sudo systemctl status memcached` and try again.
You get NOMEMCACHED (code 64)	The module is installed but memcached is not on the host.	You are on an image other than the product's: install memcached or use the right AMI.
Lots of `evictions` in `status`	The cache is small for what you store: items are evicted to make room.	Raise the percentage with `optimize --memory-pct` or move to an instance with more RAM.
The cache is suddenly empty	The service restarted, and memcached persists nothing to disk.	Normal after `optimize`. To apply without restarting, use `--no-restart`.
The client rejects the certificate	It is self-signed and unique to each instance.	Trust it in your client or validate its fingerprint with `tls show`.

Stuck with the Memcached module?

Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.

Contact support

Run your cache without touching files

What this module does #

Quick guide #

Check the service status

Connect to the cache

Tune the cache size

Create SASL users

Review the TLS certificate

Synopsis #

Subcommands #

Arguments and flags #

Files and paths #

Exit codes and logs #

Troubleshooting #

Stuck with the Memcached module?