Share

Database and mail server monitors

Nine monitor types talk to a service in its own protocol instead of only opening its port: MySQL / MariaDB, PostgreSQL, Redis, MongoDB, Memcached, SMTP, IMAP, POP3 and FTP. They can sign in, check TLS and the certificate, and (for databases) read a few health figures and judge them against rules. The protocols are implemented inside the app, so no PHP database extension is needed on the main server or on a probe.

Nothing is ever written: database queries run in a read-only transaction, no mail is sent, and the FTP check never opens a data connection.

Common settings

Host (in the Basics card) is a host name or IP. Private and internal addresses are refused like for every monitor, and the connection goes to the address that passed that check. The Service connection card holds the rest:

FieldMeaning
PortEmpty uses the standard port of the service (see below). A host:port target works too
TLSDefault for this service, Off, When the server offers it, Required (STARTTLS / TLS request) or Implicit TLS from the first byte
Certificate checksDefault for this service, Trusted chain, host name and expiry, Host name and expiry (self-signed allowed) or None, encryption only
User name, PasswordOptional sign-in (not shown for Memcached)

Standard ports and defaults:

TypePortTLS modesDefault TLSDefault certificate check
MySQL / MariaDB3306Off, When offered, RequiredWhen offeredNone
PostgreSQL5432Off, When offered, RequiredWhen offeredNone
Redis6379Off, ImplicitOffNone
MongoDB27017Off, ImplicitOffNone
Memcached11211Off, ImplicitOffNone
SMTP25 (465 implicit)all fourWhen offered (Implicit on 465)Full
IMAP143 (993 implicit)all fourWhen offered (Implicit on 993)Full
POP3110 (995 implicit)all fourWhen offered (Implicit on 995)Full
FTP21 (990 implicit)all fourWhen offered (Implicit on 990)Full

Choosing a TLS mode the service does not support is refused when you save.

TLS and certificates

  • When the server offers it upgrades the connection when the server advertises it (STARTTLS, STLS, AUTH TLS, the MySQL TLS flag, PostgreSQL's TLS request) and carries on without TLS otherwise.
  • Required makes the check Down when the server does not offer TLS.
  • Implicit starts TLS on the first byte (ports 465, 993, 995, 990, or a TLS-only Redis/MongoDB/Memcached).
  • Trusted chain, host name and expiry needs a certificate that is trusted, matches the host and has not expired. Host name and expiry allows self-signed certificates but still checks the name and the date. None only encrypts.
  • Data that arrives before the TLS handshake is refused, as protection against injection.

The result stores the TLS version, cipher, subject, issuer, names and days left. When TLS is used and certificate checking is not None, the expiry date is saved on the monitor, so the daily SSL expiring alert covers this server's certificate too (warning window as set on the monitor, 14 days by default).

Credentials

The user name and password are stored like every monitor password: encrypted at rest and decrypted only for the check. Leaving the password empty on edit keeps the saved one; Remove the saved password clears it. The password (and its base64 and URL-encoded forms) is replaced by *** in errors and result details.

A password that would travel in clear text (SMTP, IMAP, POP3, FTP sign-in, PostgreSQL cleartext auth) is only sent after TLS is up. With TLS set to Off it is sent anyway; otherwise the check is Down with "Refusing to send the password without TLS". FTP anonymous / ftp sign-ins are allowed without TLS.

Timing and results

The whole check, connection included, must finish within the monitor's Timeout. A server that sends more than 4 MB is cut off. Each result stores the time of every stage (connect, tls, greeting, auth, query, stats …), the IP, port and TLS mode, and the type's figures below; open details next to a result on the monitor page to see them, or read them through the API.

Database checks

The Database checks card (MySQL, PostgreSQL, Redis, MongoDB, Memcached):

FieldTypesMeaning
DatabaseMySQL (optional), PostgreSQL (default: the user name), MongoDB (authentication database, default admin)Letters, digits, _ $ . -, up to 64 characters
QueryMySQL, PostgreSQLSee Read-only query. Empty = SELECT 1
Expected valueMySQL, PostgreSQLThe first column of the first row must equal this text
Max replication lag (s)MySQL, PostgreSQL, Redis1–604800
Max connections used (%)MySQL, PostgreSQL, MongoDB, Memcached1–100
Max memory used (%)Redis, Memcachedof maxmemory (Redis) or limit_maxbytes (Memcached)
Required roleRedis, MongoDBAny, Primary / master or Replica / secondary
Do not read server statisticsall fiveSkips the statistics queries. They are still read when one of the rules above is set

Read-only query

The query must be a single SELECT or SHOW statement, at most 2,000 characters, with no comments (--, /* */, #), no second statement, no SELECT … INTO and no locking read (FOR UPDATE, FOR SHARE, LOCK IN SHARE MODE). A trailing ; is removed. Anything else is refused when you save. The query runs between START TRANSACTION READ ONLY (MySQL) or BEGIN READ ONLY (PostgreSQL) and ROLLBACK. A query error makes the check Down ("Query failed: …").

SELECT COUNT(*) FROM orders WHERE created_at > NOW() - INTERVAL 1 HOUR
SHOW GLOBAL STATUS LIKE 'Threads_connected'

Give the monitor its own database user with only the rights the query needs.

MySQL / MariaDB

Reads the server greeting (version, TLS support), then signs in with mysql_native_password, caching_sha2_password (MySQL 8; the full exchange needs TLS or the server's RSA key) or sha256_password. Without a user name only the greeting is checked.

Figures: threads connected and running, uptime, slow queries, questions, max used connections, max_connections, connections %, read_only, and replication from SHOW REPLICA STATUS (or SHOW SLAVE STATUS on older servers): IO and SQL thread state and seconds behind. Reading the replication status needs the REPLICATION CLIENT right. Whatever the user is not allowed to read is noted in the details (stats_error) and does not make the check Down; note that a rule whose figure could not be read is then not applied either, so give the monitor user enough rights for the rules you set.

Rules: on a replica with Max replication lag set, the check is Down when replication stopped, the lag is unknown, or it is above the limit. Max connections used compares threads connected with max_connections.

PostgreSQL

Asks for TLS first (unless TLS is Off), then signs in with trust, cleartext password, MD5 or SCRAM-SHA-256. With no user name it signs in as postgres.

Figures: backends in use, max_connections, connections %, whether the server is in recovery (a standby), the number of connected replicas, replication lag (on a standby: time since the last replayed transaction, 0 when caught up; on a primary: the largest replay lag of its replicas) and uptime.

Rules: Max replication lag applies to standbys and to primaries with replicas; "lag unknown" (nothing replayed yet) is Down too. Max connections used as for MySQL.

Redis

Signs in with AUTH password, or AUTH user password for an ACL user when a user name is set, then sends PING (it must answer PONG) and reads INFO. A server that needs a password and has none set is Down with "NOAUTH".

Figures: version (Valkey too), mode, uptime, clients, used memory, maxmemory and memory %, hit ratio, evicted keys, operations per second, total keys, role, and replication (link status and seconds since the last contact on a replica, the largest replica lag on a master).

Rules: Required role (master or replica), Max memory used (only when maxmemory is set), Max replication lag (a replica whose link is not up is Down too). When INFO is refused and a rule is set, the check is Down.

MongoDB

Sends hello (or isMaster on old servers) and buildInfo, signs in with SCRAM-SHA-256 or SCRAM-SHA-1 against the authentication database when a user name is set, then reads serverStatus.

Figures: role (primary, secondary, standalone, mongos, arbiter), replica set name, hosts and primary, version, current and available connections and connections %, operation counters, uptime and resident memory.

Rules: Required role Primary / master accepts a primary or a standalone server; Replica / secondary needs a secondary. Max connections used.

Memcached

Sends stats; Memcached has no sign-in. Figures: version, uptime, current and max connections, bytes and limit_maxbytes, items, hit ratio and evictions. Rules: Max memory used and Max connections used.

Mail server checks

SMTP

Reads the 220 greeting, sends EHLO (falling back to HELO), upgrades with STARTTLS according to the TLS mode and sends EHLO again. EHLO name (on the SMTP card) is the name the check introduces itself with; empty uses the server's host name. The banner, the advertised extensions and the maximum message size are stored.

With a user name it signs in with AUTH PLAIN or AUTH LOGIN and expects 235; a server that offers neither is Down. The check ends with QUIT; no message is sent.

IMAP

Reads the greeting (* OK or * PREAUTH), asks for CAPABILITY, upgrades with STARTTLS when the mode says so, and stores the capabilities. With a user name it signs in with LOGIN, or AUTHENTICATE PLAIN when the server disables LOGIN, then logs out.

POP3

Reads the +OK greeting, asks for CAPA, upgrades with STLS when the mode says so. With a user name it signs in with USER / PASS and reads STAT, so the number of messages and the mailbox size are stored. Then QUIT.

FTP

Reads the 220 greeting and FEAT, upgrades with AUTH TLS (explicit FTPS) according to the mode, or uses implicit TLS on port 990. With a user name (anonymous works) it signs in, sets PBSZ 0 / PROT P when TLS is up, and stores the current directory from PWD.

Path that must exist (on the FTP card, needs a user name): a file is checked with SIZE (its size is stored), a directory with CWD. "Path not found" is Down. No data connection is ever opened, so nothing is listed or downloaded.

Through the API

Create these monitors through the API with type set to mysql, postgres, redis, mongodb, memcached, smtp, imap, pop3 or ftp, the host in url, port, the credentials in http_auth_user / http_auth_pass, and the settings in config:

{
  "type": "postgres",
  "name": "Orders DB",
  "url": "db1.example.com",
  "port": 5432,
  "http_auth_user": "monitor",
  "http_auth_pass": "secret",
  "config": {
    "tls_mode": "require",
    "tls_verify": "name",
    "db_name": "shop",
    "query": "SELECT 1",
    "max_lag": 30,
    "max_conn_pct": 90
  }
}

config keys: tls_mode (off, auto, require, implicit), tls_verify (full, name, none), db_name, query, expect_value, no_stats, max_lag, max_conn_pct, max_mem_pct, require_role (master, replica), ehlo_name, ftp_path.

Was this page helpful?

One click helps us improve these docs.

Share this pagePlain links - no trackers, nothing loaded until you click.