Configuration¶

This page shows where the cache's configuration lives and how to make the common changes: the memory cap, network access, the password and the TLS certificates. Make every change as root, then restart Valkey.

A restart empties the cache

Persistence is off, so restarting Valkey drops every key. Plan changes for a time when your application can refill the cache.

Where things live¶

Path	What it is
`/etc/valkey/valkey.conf`	Main configuration. Created on first boot and not overwritten afterwards.
`/etc/valkey/users.acl`	Access control list: the `cache` user and its password hash.
`/etc/valkey/credentials/cache.password`	The cache password. Root only.
`/etc/valkey/tls/`	CA and server certificates and keys.
`/usr/local/share/sushi/valkey/ca.pem`	Public copy of the CA certificate, for clients.
`/var/lib/valkey`	Working directory of the service.
`/opt/sushi/bin/valkey-cache-cli`	Helper client for the `cache` user.

Do not put passwords or private keys in valkey.conf.

What the cache user can do¶

The ACL gives the cache user a deliberately narrow set of permissions:

Keys must start with cache:.
Allowed: connection commands such as PING and SELECT 0, and reads and writes on strings, hashes, lists, sets and sorted sets.
Denied: admin, dangerous, scripting and pub/sub commands, including FLUSHALL, CONFIG, RENAME, COPY and MOVE.
The default user is off, so a connection that does not authenticate is refused.

Change the memory cap¶

The cache holds at most 1536 MiB and evicts the least recently used keys when it is full, including keys without a TTL. On a larger instance, raise the cap in /etc/valkey/valkey.conf:

maxmemory 1536mb
maxmemory-policy allkeys-lru

Keep maxmemory well below the instance's memory, so the operating system and the allocator still fit. Then restart:

sudo systemctl restart valkey

Reach the cache from your VPC¶

By default Valkey listens on 127.0.0.1 only. To let other hosts in your VPC connect:

In /etc/valkey/valkey.conf, add the instance's private address to the bind line, keeping 127.0.0.1 so the helper client still works:
```
bind 127.0.0.1 <private-ip>
```
Issue a server certificate that includes that address (see below). The certificate created on first boot covers only localhost and 127.0.0.1, so clients that verify the server name would reject it.
In the instance's security group, allow TCP 6379 only from your application's security group.
Restart Valkey and give your clients a copy of /usr/local/share/sushi/valkey/ca.pem.

Keep it private

Do not bind 0.0.0.0 or open port 6379 to the internet. Keep TLS on and keep the default user off.

Issue a server certificate for a private address¶

This signs a new server certificate with the instance's own CA, the same way first boot does, with your private address added. Replace <private-ip> before you run it:

sudo bash -euo pipefail <<'CERT'
cd /etc/valkey/tls
ip=<private-ip>
umask 077
openssl genrsa -out server.key.new 2048
openssl req -new -key server.key.new -out server.csr -subj '/CN=localhost'
printf 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:%s\n' "$ip" > san.ext
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
  -days 825 -sha256 -out server.pem.new -extfile san.ext
rm -f server.csr san.ext ca.srl
mv server.key.new server.key
mv server.pem.new server.pem
chown root:valkey server.key && chmod 0640 server.key
chown root:root server.pem && chmod 0644 server.pem
CERT
sudo systemctl restart valkey

Rotate the password¶

The ACL stores a SHA-256 hash of the password, written as # followed by 64 lowercase hex characters. To rotate, write a new password file and the matching hash, then restart:

sudo bash -euo pipefail <<'ROTATE'
umask 077
creds=/etc/valkey/credentials
openssl rand -base64 24 | tr -d '\n' > "$creds/cache.password.new"
printf '\n' >> "$creds/cache.password.new"
hash=$(tr -d '\n' < "$creds/cache.password.new" | sha256sum | cut -d' ' -f1)
sed -i "s/^user cache on #[0-9a-f]\{64\}/user cache on #${hash}/" /etc/valkey/users.acl
chown root:valkey /etc/valkey/users.acl && chmod 0640 /etc/valkey/users.acl
mv "$creds/cache.password.new" "$creds/cache.password"
chmod 0600 "$creds/cache.password"
systemctl restart valkey
ROTATE

Then update the password in your application's secret store.

Rotate the TLS certificates¶

The certificates created on first boot are valid for 825 days. First boot never replaces half of an identity, so remove the files as a set and let the first-boot service create new ones.

To replace only the server certificate, keeping the CA your clients trust:

sudo systemctl stop valkey
sudo rm /etc/valkey/tls/server.pem /etc/valkey/tls/server.key
sudo systemctl restart sushi-valkey-firstboot
sudo systemctl start valkey

To replace the CA as well, remove all four files instead:

sudo systemctl stop valkey
sudo rm /etc/valkey/tls/ca.pem /etc/valkey/tls/ca.key \
  /etc/valkey/tls/server.pem /etc/valkey/tls/server.key
sudo systemctl restart sushi-valkey-firstboot
sudo systemctl start valkey

After a CA rotation, give your clients the new /usr/local/share/sushi/valkey/ca.pem. If you had added a private address, issue its server certificate again.

Things to leave alone¶

Do not turn the default user on, and do not add requirepass.
Do not set tls-auth-clients yes unless you also issue client certificates.
Do not enable a plaintext port.