pop3

pop3 checks a mail server that serves mailboxes by POP3, such as Dovecot. MMWatchdog talks POP3 with the server. MMWatchdog waits for the server's greeting, switches to encryption when the check's connection_security says so, and quits. The check logs in to no mailbox.

For a mail server that serves mailboxes by IMAP, use imap; for one that accepts mail, smtp. To be warned before the POP3 server's certificate expires, add a tls check on port 995, encrypted from the first byte. A tls check does not negotiate STARTTLS. STARTTLS starts a connection without encryption, then switches the connection to encryption after a protocol command. The pop3 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 pop3 module page describes what is particular to POP3.

Inputs

  • address (string; required): The address of the POP3 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, or unencrypted; 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 POP3 conversation ends within the check group's time_limit_per_run (timings of a check group). The message says the POP3 server at mail.example.com:995 answers, and its certificate is valid, or the POP3 server at 127.0.0.1:110 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:110: connect: connection refused, or the connection to 127.0.0.1:110 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:995 did not start: and the reason.
  • A step of the conversation fails. The message names the step and gives the server's answer or the reason, such as the POP3 server at mail.example.com:995: its greeting: no answer within the time limit of the run. The steps are its greeting, MMWatchdog's request for encryption, its answer to STLS, the switch to encryption, MMWatchdog's QUIT, and its answer to QUIT. A greeting or an answer that does not start with +OK fails its step, with the server's line in the message.
  • The server sends more than MMWatchdog reads, 64 KiB before or after the switch to encryption. The step's message 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 POP3 server at mail.example.com:110 refused to switch to encryption, which connection_security: starttls requires. Its answer to STLS: -ERR 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 POP3 port of a mail server

# /etc/mmwatchdog/check_groups/pop3_mailboxes.yml
check_groups:
  pop3_mailboxes:
    check_every: 1m
    time_limit_per_run: 10s
    alert_after_failing_for: 3m
    recovered_after_healthy_for: 1m
    checks:
      mail_server_serves_pop3:
        pop3:
          address: mail.example.com:995
          connection_security: implicit_tls
        alert_severity: warn

Once a minute, MMWatchdog on the node connects to port 995 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 quits. 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_pop3.yml
check_groups:
  local_pop3:
    check_every: 1m
    time_limit_per_run: 10s
    alert_after_failing_for: 3m
    recovered_after_healthy_for: 1m
    checks:
      dovecot_serves_pop3:
        pop3:
          address: mail.internal.example.com:110
          connection_security: starttls
          trusted_certificate_authority_file: /etc/mmwatchdog/secrets/internal-ca.pem
        alert_severity: warn

MMWatchdog connects to port 110 without encryption, waits for the greeting, and sends STLS, the POP3 command for STARTTLS. MMWatchdog verifies the certificate against the certificates in /etc/mmwatchdog/secrets/internal-ca.pem because a private certificate authority signed the server's certificate. The certificates in /etc/mmwatchdog/secrets/internal-ca.pem replace the node's system certificates for the check. MMWatchdog reads /etc/mmwatchdog/secrets/internal-ca.pem again for each run. A server whose encryption is turned off answers STLS with -ERR, and the check fails with that answer.

How it works

  1. 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.
  2. MMWatchdog reads the server's greeting, which must start with +OK.
  3. With starttls, MMWatchdog sends STLS and expects +OK. Then MMWatchdog switches to encryption and verifies the certificate.
  4. MMWatchdog sends QUIT, expects +OK, 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 it does so, with the server sent more data than MMWatchdog reads from the server.

The usual ports are 995 with implicit_tls and 110 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 in the connection to a mail server. The messages of a run are under when the check fails.

Tested on

  • Go tests: TestMailServerChecks in internal/checksandalerts/protocol_checks_test.go runs the check against a stand-in mail server with each connection_security. Cases cover a certificate that only trusted_certificate_authority_file makes valid and a file missing at a run and at mmwatchdog validate. Further cases cover a server of another protocol and a silent server.

    A server refuses STLS with Dovecot's words and answers a check without encryption. Another server closes the connection instead of answering. TestMailServerChecks also tests the validation errors. The 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. With Dovecot running, port 110 with unencrypted and starttls, and port 995 with implicit_tls, are each healthy. A stopped Dovecot fails the unencrypted check. With Dovecot's encryption turned off, the starttls check fails and says that the server refused to switch. Dovecot without encryption answers the unencrypted check.

MMWatchdog speaks POP3 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, switches to encryption, and lets the client quit serves connections; a check that needs no password leaves no credential on the node.
  • connection_security is 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: true permits encryption without server authentication when the operator explicitly chooses it.
  • A refused STLS gives the server's own answer. A server whose encryption is turned off is a fault of its 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.
  • pop3 is a core module. Checking that a mail server serves mailboxes is common work, so mmwatchdog includes and tests the check.

This page is docs/reference/modules/pop3.md in the MMWatchdog repository.