Redis Authentication

After reading this page you can require a password on the Redis instance rConfig V8 Pro uses, confirm the fix from the command line, and clear the Redis Auth warning straight away. It also covers every message the check and the commands can print, and what to do about each one.

When to use this page

Use this page when the Redis Auth health check fails, when the redis_auth row on System Settings >> System Optimization shows Needs Optimization, when php artisan rconfig:redis-security-check exits non-zero, or when Horizon logs NOAUTH errors after a Redis password change. Installs that predate V8.4.1 ran Redis with no password, so most servers land here once after upgrading.

Why does Redis need a password?

rConfig uses Redis for its job queue, cache, and sessions. Horizon workers take jobs off the queue and run them, so anything that can write to Redis can make a worker run code. A Redis password is the control that closes this.

Binding Redis to 127.0.0.1 is not enough on its own. Any process on the server can reach a loopback listener, including connections rConfig itself opens on behalf of devices. That is why rConfig reports the bind address and protected mode for context only, and never treats them as a pass.

What do the check and the optimisation row report?

rConfig checks the Redis authentication state in two places. Both read the same status, so they never disagree.

Redis Auth health check. Runs with the other system health checks every five minutes.

Result	Message	Meaning
Ok	Redis requires authentication.	Redis rejects clients without a password. Nothing to do.
Failed	Redis has no password set. Run: php artisan rconfig:redis-secure	Redis accepts any local client. Follow the steps below.
Warning	Redis is unreachable; authentication state could not be determined.	The check could not connect to Redis at all. See Redis is unreachable.

redis_auth row on System Optimization (V8.4.1+). Navigate to System Settings >> System Optimization. The row sits in the Redis Settings card, directly under the redis connection row.

Current Value	Status	Information column
password required	Optimal	The bind address and protected mode, marked context only
no password	Needs Optimization	Run: php artisan rconfig:redis-secure (as root or the web user)
unreachable	Needs Optimization	Redis could not be reached, so its authentication state is unknown

The Edit in line reads .env (REDIS_PASSWORD). Unlike the rest of the page, this row is not cached for 15 minutes. It is recalculated every time the page loads, so it turns Optimal as soon as Redis requires a password.

The same state is available from the command line with php artisan rconfig:redis-security-check, which is read only and safe to run at any time.

Prerequisites

• rConfig V8 Pro V8.4.1 or later. On older releases, update first (see How to update rConfig V8 Pro).
• Shell access to the rConfig server as root or with sudo. In Docker, access to docker exec on the host.
• To know whether other rConfig nodes or any other application use the same Redis instance. If one does, read Redis shared with other nodes before you start.

How do I secure Redis?

Bare metal (Rocky, RHEL, Ubuntu)

1. Go to the rConfig folder.

   cd /var/www/html/rconfig8/current

2. Check the current state.

   php artisan rconfig:redis-security-check

   On an unsecured install the output looks like this:

   ERROR  Redis has no password set. Run: php artisan rconfig:redis-secure
   
   Password required ............................................. no
   App can authenticate .......................................... yes
   Bind (context only) ................................. 127.0.0.1 -::1
   Protected mode (context only) ................................. yes

   The exit code tells scripts the same thing: 0 means a password is required, 1 means Redis has no password, 2 means Redis could not be reached.

3. Preview the change. Nothing is altered.

   php artisan rconfig:redis-secure --dry-run

   If the preview prints a red THIS REDIS MAY BE SHARED BY OTHER APP NODES banner, stop and read Redis shared with other nodes first.

4. Secure Redis.

   php artisan rconfig:redis-secure

   The command generates a 64 character password, writes it to REDIS_PASSWORD in .env, rebuilds the config cache if one exists, requires the password on the running Redis with CONFIG SET requirepass, and saves it to the Redis config file with CONFIG REWRITE. It then signals the queue workers, Horizon, and the SNMP trap handler to restart so they reconnect with the new password. Supervisor relaunches each of them. A successful run ends with:

   INFO  Generated a new Redis password and required it on the live instance.
   INFO  Broadcast queue restart signal.
   INFO  Signalled Horizon to restart; supervisor will relaunch it with the new password.
   INFO  Signalled the SNMP trap handler (if running) to restart.
   INFO  Redis is now secured. Verify with: php artisan rconfig:redis-security-check

   If it prints a warning instead, find the message under Troubleshooting.

5. Verify the fix.

   php artisan rconfig:redis-security-check
   echo $?

   You should see Redis requires authentication., both Password required and App can authenticate set to yes, and an exit code of 0.

6. Clear the warning now rather than waiting for the next five minute run.

   php artisan health:check

   The output includes Running check: Redis Auth... followed by Redis requires authentication.. Then reload System Settings >> System Optimization. The redis_auth row shows Optimal on the next page load, without clicking Refresh.

Docker

In the rConfig V8 Pro container, Redis runs inside the container under Supervisor, and .env lives in the mounted data directory. Run the same commands inside the container. The examples use the default container name rconfig8docker-app-1.

1. Check the current state.

   docker exec -it rconfig8docker-app-1 php artisan rconfig:redis-security-check

2. Preview, then secure Redis.

   docker exec -it rconfig8docker-app-1 php artisan rconfig:redis-secure --dry-run
   docker exec -it rconfig8docker-app-1 php artisan rconfig:redis-secure

3. Verify the fix and clear the warning.

   docker exec -it rconfig8docker-app-1 php artisan rconfig:redis-security-check
   docker exec -it rconfig8docker-app-1 php artisan health:check

Do not set REDIS_PASSWORD in the environment: block of your compose file. A real environment variable overrides .env, so the application would keep using that value while Redis requires the one the command wrote.

Recheck after every image update

.env survives a container recreate because it is on the mounted volume. The Redis config inside the container may not. After docker compose up -d with a new image, run rconfig:redis-security-check. If Password required is no and App can authenticate is no, follow Redis lost its password.

What happens to the SNMP trap handler?

The SNMP trap handler is a long-running process that holds its own Redis connection, separate from Horizon. rconfig:redis-secure sets a restart signal in the cache. The running handler sees it, logs Restart requested; exiting so supervisor relaunches the handler with fresh config. to storage/logs/snmp-trap-handler.log, and exits. Supervisor starts it again with the new password.

This works whether the handler runs as root or as the web server user, and needs no sudo supervisorctl call. If the handler is not running, the signal does nothing. If traps stop arriving after you secure Redis, restart it by hand:

sudo supervisorctl restart rconfig-snmp-trap

See SNMP Traps CLI & Setup for the Supervisor program.

How do I rotate the Redis password?

Rotate the password if it may have leaked, for example after .env was copied somewhere it should not have been.

cd /var/www/html/rconfig8/current
php artisan rconfig:redis-secure --force
php artisan rconfig:redis-security-check

--force generates and applies a new password even when one is already set. It connects with the current password to change it, so Redis must accept the value in .env. Every other node or application that shares this Redis instance must be given the new value.

Troubleshooting

Redis is unreachable

The health check returns a warning, the redis_auth row shows unreachable, and rconfig:redis-security-check exits 2. The check could not open a connection, so it cannot say whether a password is required.

1. Check that Redis is running.

   # RHEL, Rocky, Alma 8 and 9
   sudo systemctl status redis
   
   # EL10 (Valkey)
   sudo systemctl status valkey
   
   # Ubuntu
   sudo systemctl status redis-server

2. Start it if it is stopped, and enable it at boot with sudo systemctl enable --now and the same service name.

3. Confirm rConfig points at the right host and port. The check connects to REDIS_HOST and REDIS_PORT from .env (default 127.0.0.1 and 6379).

   grep -E '^REDIS_(HOST|PORT)=' /var/www/html/rconfig8/current/.env
   redis-cli -h 127.0.0.1 -p 6379 ping

   PONG or NOAUTH Authentication required both mean Redis is listening. A connection error means it is not, or is on another address. On EL10, run valkey-cli in place of redis-cli.

4. Rerun php artisan rconfig:redis-security-check and continue from the result.

“REDIS_PASSWORD is set in .env but the live Redis does not accept it (desync)”

rconfig:redis-secure stops rather than overwrite a password it did not set. .env and Redis disagree, so Horizon cannot connect either. Pick one:

• Keep the password Redis already has. Copy the requirepass value from your Redis config file into REDIS_PASSWORD in .env, run php artisan config:cache if your install caches config, and restart Horizon with php artisan horizon:terminate.
• Replace it with a fresh password. If Redis requires a password you know, put that value in .env first, then run php artisan rconfig:redis-secure --force. --force authenticates with the value in .env, so it cannot change a password it does not know.

Redis lost its password after a restart

rconfig:redis-security-check shows Password required no and App can authenticate no. .env holds a password, but Redis came back without one. This happens when the password was never saved to the Redis config file, or when a Docker container was recreated. Redis then rejects the password rConfig sends, so the queue stops too.

Clear the stale value and secure Redis again:

1. Set REDIS_PASSWORD=null in .env.
2. Run php artisan rconfig:redis-secure. It generates a new password and applies it to both sides.
3. If the command prints the CONFIG REWRITE warning, fix that next so it does not happen again.

“CONFIG REWRITE failed: the password is live but not persisted”

Redis accepted the password but could not save it to its config file, usually because it was started without one. The password works now and is lost when Redis restarts, which brings the warning back and locks the queue out. Add it to the config file by hand:

1. Read the password rConfig set.

   grep '^REDIS_PASSWORD=' /var/www/html/rconfig8/current/.env

2. Add or replace the requirepass line in the Redis config file with that value, then restart Redis.

   RHEL, Rocky, Alma

   sudo vi /etc/redis/redis.conf    # RHEL 8: /etc/redis.conf
   # requirepass <value of REDIS_PASSWORD>
   sudo systemctl restart redis

   EL10 (Valkey)

   sudo vi /etc/valkey/valkey.conf
   # requirepass <value of REDIS_PASSWORD>
   sudo systemctl restart valkey

   Ubuntu

   sudo vi /etc/redis/redis.conf
   # requirepass <value of REDIS_PASSWORD>
   sudo systemctl restart redis-server

3. Restart Horizon so it reconnects, then verify.

   cd /var/www/html/rconfig8/current
   php artisan horizon:terminate
   php artisan rconfig:redis-security-check

“The new password could not be verified against the live instance”

The password was applied but a fresh connection with it failed, and the command exits with a failure code. Run php artisan rconfig:redis-security-check. If Password required is yes and App can authenticate is no, follow the desync steps above.

App can authenticate reports no, or Horizon logs NOAUTH

Redis requires a password, so the health check passes, but the application is not sending the right one and queued jobs fail. This happens when the password in .env is wrong, when a cached config still holds an old value, or when Horizon kept a connection opened before the change. It also happens if you ran rconfig:redis-secure --no-restart and never restarted the workers.

cd /var/www/html/rconfig8/current
php artisan rconfig:redis-security-check     # confirm App can authenticate: no
php artisan config:cache                     # only if your install caches config
php artisan horizon:terminate                # Supervisor relaunches Horizon

If it still reports no, the value in .env does not match Redis. Follow the desync steps above.

Redis shared with other nodes

A multi-node or HA deployment can point several rConfig servers at one Redis. Every one of them loses access as soon as a password is set, because their .env still has no password. rconfig:redis-secure looks for two signs of sharing: a REDIS_HOST that is not a local address, and clients connected to Redis from other hosts. If it finds either, it prints a red banner and lists what it saw:

 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 THIS REDIS MAY BE SHARED BY OTHER APP NODES. They are now locked out
 until REDIS_PASSWORD is copied to their .env and they are restarted.
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  • Clients are connected from other hosts: 10.0.20.12, 10.0.20.13.

With --dry-run, the banner says Securing it would lock them out instead, and nothing changes. The command does not manage the other nodes. Run it on one node, then on every other node:

1. Copy REDIS_PASSWORD from the first node’s .env into this node’s .env.
2. Run php artisan config:cache if the node caches config.
3. Run php artisan horizon:terminate and php artisan queue:restart, and restart the SNMP trap handler if the node runs one.
4. Run php artisan rconfig:redis-security-check and confirm App can authenticate is yes.

Do not run rconfig:redis-secure on the other nodes. Each run generates a different password and locks out the nodes you already updated. See High Availability options for multi-node deployments.

Common gotchas

• redis-cli now says NOAUTH. That is the fix working. Authenticate without putting the password on the command line, where it lands in shell history and the process list: redis-cli --askpass, or REDISCLI_AUTH="$(grep '^REDIS_PASSWORD=' .env | cut -d= -f2-)" redis-cli ping.
• Bind and protected mode are not a fix. Changing the bind address or protected mode never clears the warning. Only a required password does.
• The warning comes back after a reboot. The password was never saved to the Redis config file. Follow the CONFIG REWRITE steps above.
• Running the command as root. That is supported. When run as root, the rebuilt config cache is handed back to the web server user so the UI can still read it.

What’s next

• Look up every rconfig:redis-secure option in the CLI commands reference
• Redis Memory Optimization: the rest of the Redis Settings card
• Security Hardening Guide: Redis alongside authentication, network, and server hardening