# How to Configure Redis maxmemory on an xCloud Server via SSH

> Set a Redis memory limit and eviction policy on an xCloud server over SSH with a live CONFIG SET, no Redis restart and no downtime for your sites.

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

- SSH access to the xCloud server. See [how to generate and add SSH keys in xCloud](/docs/how-to-generate-and-add-ssh-keys-in-xcloud/).
- A user with `sudo` or root access. See [sudo users and site users in xCloud](/docs/usudo-users-and-site-users-in-xcloud/).
- The **server-level** Redis password. See the next section.

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](/docs/how-to-find-the-redis-credentials/).

## Step 1: Connect to the server

From your terminal:

```bash
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](/docs/access-web-terminal-in-xcloud/).

## Step 2: Confirm the Redis service and current configuration

```bash
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

```bash
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.

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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

- xCloud: [How Caching Works in xCloud](/docs/how-caching-works-in-xcloud/)
- xCloud: [How to Find the Redis Credentials](/docs/how-to-find-the-redis-credentials/)
- Redis: [Key eviction and the maxmemory directive](https://redis.io/docs/latest/develop/reference/eviction/)

If you run into any issues with this setup, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/) for help.