redis
redis asks a Redis server for an answer, over TCP, in the Redis protocol:
the check sends PING and expects PONG. With a password file, MMWatchdog
logs in first. MMWatchdog speaks the protocol itself, so the node needs no
Redis program for the check. The redis check works for a server that
speaks the Redis protocol under another name, such as Valkey.
address is the server's address, written as host:port, such as
127.0.0.1:6379. The redis check has no default port, so the configured
address shows where the check connects. connection_security is required
on every check, including a check without a login: verified_tls encrypts
and verifies the certificate; unencrypted sends without encryption.
Set up
A server without a password needs nothing. For a server with a password, put the password on one line in a file that only root can read. MMWatchdog reads the password file as root. The command reads the password from the terminal: type the password, press Enter, and then Ctrl-D.
sudo install -d -m 0700 /etc/mmwatchdog/secrets
sudo install -m 0600 /dev/stdin /etc/mmwatchdog/secrets/redis
mmwatchdog validate refuses a password file that its group or other accounts
can read without explicit permission (credential files that other accounts can use).
Inputs
connection_security(verified_tlsorunencrypted; required): Required on every check: verified_tls encrypts and verifies the server certificate; unencrypted sends without encryption, including any login.dangerously_skip_server_certificate_check(boolean; optional): With true, encrypt the connection without checking the server's certificate or identity. By default, verify the server's certificate.trusted_certificate_authority_file(string; optional): With verified_tls: the absolute path of a file of PEM certificates trusted in place of the system authorities.address(string; required): The address of the Redis server, as host:port.login_user(string; optional): The account that the check logs in as, on a server that has accounts. It needs login_password_file.login_password_file(string; optional): The absolute path of a file that holds the password, on one line. MMWatchdog reads it for each run.
When the check fails, and when it cannot check
- The check fails when the connection does not open, when the server
closes the connection before its answer is complete, and when the answer
does not arrive within the check group's
time_limit_per_run. The check also fails when the server answers with an error, such asNOAUTH Authentication required.for a server that needs a password and got none,WRONGPASSfor a wrong password, orLOADING Redis is loading the dataset in memorywhile a server starts. The message then holds the server's words. An answer that is not a Redis server's answer fails the check too. - MMWatchdog cannot check when MMWatchdog cannot read the password file
or the file named in
trusted_certificate_authority_file. The run is then unknown.
A failed run starts or continues the check's
failing time. An unknown run opens a
cannot-check incident of its own after the same waiting times, as the
design's failing time
describes. The redis module reports no measurement, so a redis check takes no limit.
Examples
A Redis server with a password
# /etc/mmwatchdog/check_groups/cache.yml
check_groups:
cache:
check_every: 1m
time_limit_per_run: 10s
alert_after_failing_for: 3m
recovered_after_healthy_for: 1m
checks:
redis_answers:
redis:
connection_security: unencrypted
address: 127.0.0.1:6379
login_password_file: /etc/mmwatchdog/secrets/redis
alert_severity: sos
Every minute, MMWatchdog on the node reads /etc/mmwatchdog/secrets/redis, opens a TCP
connection to 127.0.0.1:6379, logs in with the password (AUTH), and
sends PING. When the server answers PONG, the run is healthy, with the
message the Redis server at 127.0.0.1:6379 answered PING. When the server
does not answer, or answers with an error, for 3 minutes, MMWatchdog sends an sos
alert.
A server with accounts
A server with accounts (Redis 6 and later, ACL) logs a client in as an
account. login_user names the Redis account used for the login.
Setting login_user requires setting login_password_file:
# /etc/mmwatchdog/check_groups/sessions.yml
check_groups:
sessions:
check_every: 1m
time_limit_per_run: 10s
alert_after_failing_for: 3m
recovered_after_healthy_for: 1m
checks:
session_store_answers:
redis:
connection_security: verified_tls
address: sessions.internal.example.com:6380
trusted_certificate_authority_file: /etc/mmwatchdog/internal-ca.pem
login_user: mmwatchdog
login_password_file: /etc/mmwatchdog/secrets/redis-sessions
alert_severity: warn
MMWatchdog on the node logs in to the server on
sessions.internal.example.com as the account mmwatchdog, with the
password in /etc/mmwatchdog/secrets/redis-sessions, and sends PING.
The connection to port 6380 uses TLS and trusts /etc/mmwatchdog/internal-ca.pem.
How it works
- MMWatchdog reads the password file for each run, so a changed password needs
no reload. A file that cannot be read makes the run unknown, and
mmwatchdog validateon the node refuses it. - The password never appears in a message. When a server repeats the
password in a reply, MMWatchdog replaces the password with
(the password)in the displayed reply. verified_tlsencrypts before any login or PING. MMWatchdog verifies the certificate for the host inaddress, using the system authorities ortrusted_certificate_authority_filein their place.dangerously_skip_server_certificate_check: trueskips authentication of the server while keeping encryption.unencryptedis accepted for any host, including with a login.connection_security: unencryptedmakes the choice to send without encryption visible, for example inside a private tunnel.- MMWatchdog reads at most 64 KiB of an answer, and shows what a server sent with every character replaced that changes how text is shown, as for every check of a common service (protocols and common server software).
Errors and what they mean
check_groups.cache.checks.redis_answers.redis.address: address 127.0.0.1: missing port in address. Write the address as host:port.... redis.login_password_file: required with login_user: the file that holds the password of mmwatchdog. An account always logs in with a password. Addlogin_password_file.... redis.login_password_file: must be absolute. Write the whole path, such as/etc/mmwatchdog/secrets/redis.... redis.login_user: expected one word of at most 256 bytes. An account name has no spaces.... redis.login_password_file: open /etc/mmwatchdog/secrets/redis: no such file or directory, frommmwatchdog validate. A run is unknown with theopen /etc/mmwatchdog/secrets/redis: no such file or directorymessage, without the name of the setting. Create/etc/mmwatchdog/secrets/redis.... redis.login_password_file: /etc/mmwatchdog/secrets/redis: expected one line with the password: UTF-8 text of at most 1,024 bytes, without a tab or another control character. The file is empty, or holds more than the password's one line.the Redis server at 127.0.0.1:6379 answered: NOAUTH Authentication required.The server needs a password and the check states none. Addlogin_password_file.the Redis server at 127.0.0.1:6379 answered: WRONGPASS invalid username-password pair or user is disabled.The password or account is wrong.the server at 127.0.0.1:6379 did not answer PING as a Redis server does. Another program listens at127.0.0.1:6379, such as memcached. The alert's body shows the listening program's reply, afterthe server sent:.dial tcp 127.0.0.1:6379: connect: connection refused. No program listens at127.0.0.1:6379.the connection to 127.0.0.1:6379 did not open within the time limit of the run. The connection did not open before the time limit of the run ended it.
Tested on
- Go tests:
TestRedisCheckinprotocol_checks_test.goruns the check against a stand-in server on the test machine: with and without a login, a wrong account, a password that never appears in a message, and a password file that cannot be read.TestRedisTLSchecks verified TLS, an untrusted certificate, and explicit skipping of certificate verification.TestTCPCheckSendsATextAndExpectsAReplycovers a port where nothing listens. - Real servers: the
servicessuite (service_scenarios.py) checks Redis as each distribution installs Redis, or Valkey where the distribution supplies Valkey instead of Redis. The suite'sredischeck getsPONGwithout a password, fails withNOAUTH Authentication required.once the server has a password, getsPONGafter a login, fails withWRONGPASSfor another password without showing it, fails for a memcached server, and fails while the Redis or Valkey server is stopped. The latest run passed on every target distribution (validation record). - Not verified on a real node: a login with
login_user, and a server that answers a part and then waits. Go tests cover a login withlogin_userand a server that answers a part and then waits.
Why it works this way
-
Every check states its connection security. A reader sees whether a password will travel without encryption, even across a private network.
-
TLS verifies the server by default. The certificate authority input supports private authorities; skipping verification requires the explicit dangerous setting because another machine can then pose as the server.
-
Permission refusals belong to validation and reload. Startup warns once per file; a running check continues after a mode change so the permission rule cannot stop monitoring. The credential permission rule owns the settings and the reasons.
-
The check logs in only when it states a password file.
PINGneeds no login on a server without a password, and a check of a common service logs in only where the service gives no answer without a login. -
MMWatchdog reads the password for each run. A changed password then needs no reload, and the password is never kept in the configuration.
-
The address has no default port. A reader sees on each check where it connects.
This page is docs/reference/modules/redis.md in the MMWatchdog repository.