Book a demo
Book a demo
Login

How to Configure Redis maxmemory on an xCloud Server via SSH

Updated September 22, 2026 · 6 min read

Redis is installed as a server-level service in xCloud. A change to /etc/redis/redis.conf therefore applies to every site using Redis on that server, not only one site.

This guide uses the following example:

maxmemory 350mb
maxmemory-policy allkeys-lru

What these settings mean

  • maxmemory 350mb limits the memory Redis uses for its dataset to approximately 350 MB.
  • maxmemory-policy allkeys-lru allows Redis to evict the least recently used keys when the dataset reaches the limit.
  • This is not an exact 350 MB cap on the Redis process’s total resident memory. Redis may use additional memory for connections, persistence buffers, allocator overhead, and other internal work.
  • Setting maxmemory 0 means Redis has no application-level dataset limit on a 64-bit system.

Before choosing a value, leave enough RAM for the operating system, database, PHP/Node processes, web server, and Redis overhead. If the server hosts persistent Redis data rather than disposable cache data, confirm that eviction is appropriate before using allkeys-lru.

Prerequisites

Both settings apply while Redis runs. This procedure does not restart Redis, so it does not interrupt the Redis-backed object caches on the server.

Which Redis password to use

An xCloud server has two different Redis passwords. Use the correct one, or the commands in this guide fail.

Password Where to find it Use it here?
Server Redis password (ACL user default) xCloud dashboard → your server → Settings Yes
Site Redis password (per-site ACL user) xCloud dashboard → the site page No

The site ACL user has a restricted permission set. It cannot run CONFIG GET or CONFIG SET, because config commands belong to the @admin category. If you use the site password, Redis answers WRONGPASS or NOPERM.

Only the default user has the +@all permission that CONFIG requires. For where each credential lives in the dashboard, see how to find the Redis credentials.

Step 1: Connect to the server

From your terminal:

ssh YOUR_SUDO_USER@SERVER_IP

Replace YOUR_SUDO_USER and SERVER_IP with the server’s SSH details. You can also run every command in this guide from the xCloud web terminal.

Step 2: Confirm the Redis service and current configuration

sudo systemctl status redis-server --no-pager
sudo grep -E '^[[:space:]]*(maxmemory|maxmemory-policy)[[:space:]]' /etc/redis/redis.conf || true

If no active maxmemory line appears, Redis is normally using the default value of 0, meaning no dataset limit.

Step 3: Back up the Redis configuration

REDIS_BACKUP="/etc/redis/redis.conf.bak.$(date +%Y%m%d-%H%M%S)"
sudo cp --preserve=all /etc/redis/redis.conf "$REDIS_BACKUP"
echo "Backup created: $REDIS_BACKUP"

Keep the printed backup path. You will need it for the rollback procedure.

Step 4: Apply the new limit to the running server

Both settings are changeable while Redis runs. Do not restart Redis.

Enter the server Redis password when prompted. Do not place the password directly in the command or in a support ticket.

read -rsp "Redis password: " REDISCLI_AUTH
echo
export REDISCLI_AUTH
redis-cli --user default CONFIG SET maxmemory 350mb
redis-cli --user default CONFIG SET maxmemory-policy allkeys-lru
redis-cli --user default CONFIG GET maxmemory
redis-cli --user default CONFIG GET maxmemory-policy
unset REDISCLI_AUTH

Each CONFIG SET must answer OK.

For 350mb, Redis reports 367001600 bytes. The Redis suffix mb means 1024 × 1024 bytes.

The limit is now active. It is not yet permanent. Step 5 makes it survive a restart.

Step 5: Write the change into the configuration file

A runtime change is lost if Redis restarts. Put the same values into the configuration file.

Open the configuration file:

sudo nano /etc/redis/redis.conf

Search for maxmemory and maxmemory-policy. Keep only one active, uncommented entry for each setting and set them to:

maxmemory 350mb
maxmemory-policy allkeys-lru

In nano, press Ctrl+O, then Enter to save, and Ctrl+X to exit.

Do not change xCloud’s existing bind, ACL, password, port, persistence, or supervised settings.

Do not restart Redis to load this file. The values are already active from step 4. The file only has to agree with them.

Step 6: Verify the effective Redis settings

read -rsp "Redis password: " REDISCLI_AUTH
echo
export REDISCLI_AUTH
redis-cli --user default CONFIG GET maxmemory
redis-cli --user default CONFIG GET maxmemory-policy
redis-cli --user default INFO memory | grep -E '^(used_memory_human|maxmemory_human|maxmemory_policy|mem_not_counted_for_evict):'
unset REDISCLI_AUTH

Expected key results include:

maxmemory
367001600
maxmemory-policy
allkeys-lru

Confirm that the running values and the file agree:

sudo grep -E '^[[:space:]]*(maxmemory|maxmemory-policy)[[:space:]]' /etc/redis/redis.conf

Never paste Redis passwords, ACL files, or full application configuration into a support ticket.

Step 7: Monitor after the change

Check Redis memory and eviction activity after normal traffic resumes:

read -rsp "Redis password: " REDISCLI_AUTH
echo
export REDISCLI_AUTH
redis-cli --user default INFO memory | grep -E '^(used_memory_human|maxmemory_human|maxmemory_policy|mem_not_counted_for_evict):'
redis-cli --user default INFO stats | grep -E '^(evicted_keys|keyspace_hits|keyspace_misses):'
unset REDISCLI_AUTH

A rising evicted_keys value means Redis is actively removing cached keys to remain near the configured limit. Frequent evictions together with a poor cache-hit rate may indicate that the limit is too low.

How to roll back

To undo the running change, set the previous values. For a server that had no limit, the previous values are 0 and noeviction:

read -rsp "Redis password: " REDISCLI_AUTH
echo
export REDISCLI_AUTH
redis-cli --user default CONFIG SET maxmemory 0
redis-cli --user default CONFIG SET maxmemory-policy noeviction
unset REDISCLI_AUTH

Then restore the configuration file. Use the exact backup path printed in step 3:

sudo cp --preserve=all /etc/redis/redis.conf.bak.YYYYMMDD-HHMMSS /etc/redis/redis.conf

Replace redis.conf.bak.YYYYMMDD-HHMMSS with the actual backup filename.

This rollback needs no restart either.

If Redis restarts or fails to start

Redis can restart for other reasons, such as a package upgrade or a server reboot. If Redis does not come back, do not restart it repeatedly.

Redis writes its own errors to a log file, not to the systemd journal. The journal shows only that the unit failed. Read both, in this order:

sudo systemctl status redis-server --no-pager
sudo tail -50 /var/log/redis/redis-server.log
sudo journalctl -u redis-server -n 50 --no-pager

The Redis log file holds the actual cause, for example a bad directive or a failed data load. The log path is set by the logfile directive in /etc/redis/redis.conf.

If the journal shows -- No entries --, the journal has already rotated past the event. Use the Redis log file.

After you fix the cause, start the service and confirm it:

sudo systemctl start redis-server
sudo systemctl is-active redis-server

The is-active command should return active.

Do not share passwords, ACL contents, environment files, or unredacted logs.

Notes for xCloud users

  • Redis is shared at server level, so this limit affects all sites on the server.
  • WordPress object-cache entries are generally disposable and can be rebuilt after eviction.
  • Do not use allkeys-lru if the same Redis instance contains data that must never be evicted.
  • Redis maxmemory is preferable to a strict systemd MemoryMax cap for normal cache control. A systemd cap limits the whole process and can terminate Redis if it is set without enough overhead. Configure an OS-level hard cap only when you fully understand the workload and have tested an appropriate margin.
  • A restart drops every Redis connection. Sites with an active object-cache drop-in can show “Error establishing a Redis connection” while Redis is down. This is why this guide applies the change live instead.

References

If you run into any issues with this setup, feel free to reach out to our support team for help.