imap
imap checks a mail server that serves mailboxes, such as Dovecot.
IMAP is a protocol for accessing mailboxes. MMWatchdog waits for the IMAP
server's greeting, switches to encryption when the check's
connection_security says so, and logs out. The check logs in to no mailbox.
POP3 is another protocol for accessing mailboxes. For a mail server that
serves mailboxes by POP3, use pop3. For a mail server
that accepts mail, use smtp. To be warned before the
IMAP server's certificate expires, add a tls check on
port 993, encrypted from the first byte. STARTTLS starts a connection
without encryption, then switches the connection to encryption. A tls
check does not negotiate STARTTLS.
The imap check verifies certificate validity unless explicitly disabled.
smtp, imap, and pop3 connect to a mail server in the same way:
connection_security, the verification of the server's certificate, and
trusted_certificate_authority_file work alike for all three, and the configuration files
reference describes them in
the connection to a mail server.
The imap module page describes what is particular to IMAP.
Inputs
address(string; required): The address of the IMAP server, as host:port.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.connection_security(starttls,implicit_tls, orunencrypted; required): How the connection is protected: starttls starts without encryption and switches to it, implicit_tls is encrypted from the first byte, and unencrypted is never encrypted.trusted_certificate_authority_file(string; optional): The absolute path of a file of PEM certificates that MMWatchdog trusts for this check in place of the system's.
When the check fails, and when it cannot check
A run of the check is healthy when the whole conversation ends within the
check group's time_limit_per_run
(timings of a check group).
The run's result message says the IMAP server at mail.example.com:993 answers, and its certificate is valid, or the IMAP server at 127.0.0.1:143 answers with
connection_security: unencrypted.
The run fails when:
- The connection does not open. The message is the reason that the
node's system gives, such as
dial tcp 127.0.0.1:143: connect: connection refused, orthe connection to 127.0.0.1:143 did not open within the time limit of the run. - The encrypted connection does not start with
connection_security: implicit_tls, for example because the certificate is not valid:the encrypted connection to mail.example.com:993 did not start:and the reason. - The greeting is not one of a server that is ready: `the IMAP server
at mail.example.com:993: its greeting: expected a line that starts with
- OK, received * BYE too many connections`.
- A step of the conversation fails. The message names the step, such
as
the IMAP server at mail.example.com:993: its greeting: no answer within the time limit of the run. The steps areits greeting,its answer to STARTTLS,the switch to encryption, andits answer to LOGOUT. After the step comes the server's answer, or the reason, such asthe server closed the connectionor a certificate that is not valid. - The server sends more than MMWatchdog reads, 64 KiB in one run: the message
of the step ends with
the server sent more data than MMWatchdog reads from the server. - The server refuses to switch to encryption with
connection_security: starttls. The message has the server's own answer:the IMAP server at mail.example.com:143 refused to switch to encryption, which connection_security: starttls requires. Its answer to STARTTLS: BAD TLS support isn't enabled.
The check is unknown when MMWatchdog cannot read the file that
trusted_certificate_authority_file names. The message names the file and the
reason, such as open /etc/mmwatchdog/secrets/mail-ca.pem: no such file or directory. A check that stays unknown for alert_after_failing_for sends
a cannot-check alert
(scheduling and observed state).
Every failed run counts toward the check's failing time, which decides when the alert goes out.
Examples
The encrypted IMAP port of a mail server
# /etc/mmwatchdog/check_groups/mailboxes.yml
check_groups:
mailboxes:
check_every: 1m
time_limit_per_run: 10s
alert_after_failing_for: 3m
recovered_after_healthy_for: 1m
checks:
mail_server_serves_mailboxes:
imap:
address: mail.example.com:993
connection_security: implicit_tls
alert_severity: warn
Once a minute, MMWatchdog on the node connects to port 993 of mail.example.com
with encryption from the first byte, and verifies the server's certificate
for the name mail.example.com. MMWatchdog waits for the greeting and logs
out.
When the check has been failing for 3 minutes, MMWatchdog opens an incident and
sends the warn alert.
The port that switches to encryption
# /etc/mmwatchdog/check_groups/local_mailboxes.yml
check_groups:
local_mailboxes:
check_every: 1m
time_limit_per_run: 10s
alert_after_failing_for: 3m
recovered_after_healthy_for: 1m
checks:
dovecot_serves_mailboxes:
imap:
address: mail.internal.example.com:143
connection_security: starttls
trusted_certificate_authority_file: /etc/mmwatchdog/secrets/internal-ca.pem
alert_severity: warn
MMWatchdog connects to port 143 without encryption, waits for the greeting, and
sends STARTTLS. MMWatchdog verifies the server's certificate against the
certificates in /etc/mmwatchdog/secrets/internal-ca.pem because a private
certificate authority signed the server's certificate. For the check,
the certificates in /etc/mmwatchdog/secrets/internal-ca.pem replace the
monitored node's trusted certificates. MMWatchdog reads
/etc/mmwatchdog/secrets/internal-ca.pem again for each run.
A server whose encryption is turned off answers STARTTLS with BAD
or NO, and the check fails with that answer.
How it works
- MMWatchdog opens a TCP connection to the address, written as host:port. With
implicit_tls, MMWatchdog starts the encrypted connection at once and verifies the certificate. - MMWatchdog reads the server's greeting. A server that is ready greets with a
line that starts with
* OK. A server that takes the client for already logged in greets with* PREAUTH. Any line without* OKor* PREAUTHat the start fails the check. - With
starttls, MMWatchdog sendsSTARTTLSand expectsOK. Then MMWatchdog switches to encryption and verifies the certificate. - MMWatchdog sends
LOGOUT, expectsOK, and closes the connection.
MMWatchdog reads at most 64 KiB from the server before and after the switch to
encryption. A server that sends more fails the step in which the limit is exceeded,
with the server sent more data than MMWatchdog reads from the server.
The usual ports are 993 with implicit_tls and 143 with starttls.
Errors and what they mean
The validation errors of address, connection_security, and
trusted_certificate_authority_file are the same for smtp, imap, and pop3.
The configuration files reference lists the validation errors for the three mail check modules in
the connection to a mail server.
The messages of a run are under
when the check fails.
Tested on
- Go tests:
TestMailServerChecksininternal/checksandalerts/protocol_checks_test.goruns the check against a stand-in mail server with eachconnection_security: a certificate that onlytrusted_certificate_authority_filemakes valid, a file that is missing at a run and atmmwatchdog validate, a server of another protocol, a silent server, a server that greets with* BYE, and a server that refusesSTARTTLSwith the words of Dovecot and answers a check without encryption.TestMailServerChecksalso tests the validation errors. The Go tests run on the machine that runs the suites and on every target distribution. - On a node: the services scenarios (
tests/integration/service_scenarios.py) check Dovecot as each distribution installs it, on every target distribution: port 143 withunencryptedandstarttls, and port 993 withimplicit_tls, each healthy; animapcheck of Postfix's SMTP port fails at the greeting; a stopped Dovecot fails the checks; and Dovecot with its encryption turned off fails the check withstarttls, which says that the server refused to switch, and answers the check withunencrypted.
MMWatchdog speaks IMAP itself and runs no program of the node. So the distribution of the mail server changes nothing for the check. The validation record has the latest results.
Why it works this way
- The check logs in to no mailbox. A server that greets as ready, switches to encryption, and logs the client out serves connections; a check that needs no password leaves no credential on the node.
connection_securityis required, with no default, as on an email destination. A reader sees on each check how the connection is protected (protocols and common server software).- MMWatchdog verifies certificates by default. A private authority can be named
with
trusted_certificate_authority_file.dangerously_skip_server_certificate_check: truepermits encryption without server authentication when the operator explicitly chooses it. - A refused
STARTTLSgives the server's own answer. Disabled encryption is a fault in the server's configuration, and the server's words say so. - A failed run names the step, so the person who reads the alert knows at once what the server did.
imapis a core module. Checking that a mail server serves mailboxes is common work, so the check is built intommwatchdogand tested with it.
This page is docs/reference/modules/imap.md in the MMWatchdog repository.