tls
tls opens a TLS connection from the node to an address and port, verifies
the server's certificate, and fails when the certificate expires soon.
The tls check completes the
handshake and sends nothing else, so the check works for any service that
speaks TLS, not only for HTTPS.
Choose tls to be warned before a certificate expires, and for a TLS port
that is not HTTP, such as IMAP on port 993. An http
check of an HTTPS address already verifies the certificate, so a separate
tls check is needed only for the warning before expiry or for a port that
is not HTTP. The connection is encrypted from its first byte, so address
must contain a host and a port that speaks TLS at once. Examples of TLS
ports are 443, 465, 993, and 995. A mail port that switches to encryption
with STARTTLS, such as 587, needs
smtp, which verifies the certificate too.
Inputs
address(string; required): The address to connect to, as host:port.server_name(string; optional): The name that the certificate must be valid for, when it is not the host in address.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.fail_when_certificate_expires_within(duration; required): The check fails when the certificate expires within this time, such as 30d.
Measurements
certificate_expires_in_seconds(seconds): The time until the server's certificate expires. Use fail_when_certificate_expires_within instead of a measurement limit.
A check takes no limit on these measurements: the module's own inputs say when the check fails. MMWatchdog records the readings.
When the check fails, and when it cannot check
A run is healthy when the handshake completes, the certificate is valid,
and it expires later than the required fail_when_certificate_expires_within
time from now. The message is TLS certificate is valid.
The run fails when:
- the certificate expires within
fail_when_certificate_expires_within:TLS certificate expires at 2026-11-20T12:00:00Z, the time of expiry in UTC; - the handshake fails or the certificate is not valid, such as a
certificate that expired, one for another name, or one that no trusted
certificate authority signed. The message is the cause in Go's words, such
as
tls: failed to verify certificate: x509: certificate signed by unknown authority; - the connection does not open, or does not complete the handshake
within the check group's
time_limit_per_run.
PEM is a text format for certificates, with a -----BEGIN CERTIFICATE-----
line.
MMWatchdog cannot check, and the run is unknown, when it cannot read the
trusted_certificate_authority_file, or the file holds no PEM certificate, such as
/etc/mmwatchdog/secrets/internal-ca.pem: contains no PEM certificates. An unknown
run opens no failure incident. Unknown runs open a cannot-check incident of
their own after the same waiting times
(unknown results).
A failed run starts or continues the check's failing time.
Examples
A mail server's certificate is valid for 30 more days
# /etc/mmwatchdog/check_groups/mail_certificate.yml
check_groups:
mail_certificate:
check_every: 5m
time_limit_per_run: 10s
alert_after_failing_for: 15m
recovered_after_healthy_for: 5m
tls:
address: mail.example.com:465
server_name: mail.example.com
fail_when_certificate_expires_within: 30d # alert before the certificate expires
alert_severity: warn
The check is written directly on the check group, so status shows it as
mail_certificate/tls. Every 5 minutes, MMWatchdog on the node connects to port 465
of mail.example.com, completes the TLS handshake, and verifies that the
certificate is valid for mail.example.com and signed by a certificate
authority that the node trusts. The run fails when the certificate expires
within 30 days. After 15 minutes of failing, MMWatchdog sends the warn alert.
Once the new certificate is installed, the check recovers after 5 healthy minutes.
A server with a certificate of a private certificate authority
# /etc/mmwatchdog/check_groups/internal_api_certificate.yml
check_groups:
internal_api_certificate:
check_every: 5m
time_limit_per_run: 10s
alert_after_failing_for: 15m
recovered_after_healthy_for: 5m
tls:
address: 10.0.0.5:8443
server_name: app.example.com
trusted_certificate_authority_file: /etc/mmwatchdog/secrets/internal-ca.pem
fail_when_certificate_expires_within: 14d
alert_severity: warn
MMWatchdog connects to the address 10.0.0.5, and verifies the certificate for
the name app.example.com and against the certificates of
/etc/mmwatchdog/secrets/internal-ca.pem only. The run fails when the certificate
expires within 14 days.
How it works
- The address is host:port, with a port from 1 to 65535 and no default port.
server_nameis the name that MMWatchdog sends to the server and verifies in the certificate. Withoutserver_name, the name is the host inaddress. Stateserver_namewhenaddresscontains an IP address or a host name different from the name in the certificate.- Verification is never skipped. MMWatchdog trusts the system's certificate
authorities, or, with
trusted_certificate_authority_file, only the PEM certificates intrusted_certificate_authority_file. MMWatchdog readstrusted_certificate_authority_file, of at most 1 MiB, for each run. The connection uses TLS 1.2 or later. - The time left is the measurement
certificate_expires_in_seconds: the time until the server's own certificate expires. MMWatchdog recordscertificate_expires_in_secondsin the measurement history like every measurement. Atlscheck takes no limit oncertificate_expires_in_seconds:fail_when_certificate_expires_withinis the limit. - A certificate that expires exactly at the end of
fail_when_certificate_expires_withinfails the check. mmwatchdog validateon the node readstrusted_certificate_authority_fileand refuses one that it cannot read or that holds no PEM certificate (validation).
Errors and what they mean
mmwatchdog validate and mmwatchdog reload print each error after the file, the line, and
the column, which the table leaves out. The examples are for the check
mail_certificate/tls above.
| Message | What the message means, and what to do |
|---|---|
check_groups.mail_certificate.tls.address: address mail.example.com: missing port in address |
The address has no port. Write address as host:port, such as mail.example.com:465 |
check_groups.mail_certificate.tls.address: port must be a number from 1 to 65535 |
The port is not a number from 1 to 65535 |
check_groups.mail_certificate.tls.trusted_certificate_authority_file: must be absolute |
The path does not start with / |
check_groups.mail_certificate.tls.fail_when_certificate_expires_within: expected a duration of 0s or more, such as 30s, 5m, 26h, or 7d, found the string "-1d" |
The time is negative. Write the time before expiry at which the check fails, such as 30d |
check_groups.mail_certificate.tls.fail_when_certificate_expires_within: expected a duration such as 30s, 5m, 26h, or 7d, found the string "a month" |
The time is not a number with a unit. Write the time as a number with a unit, such as 30d |
check_groups.mail_certificate.fail_when_measurement_below: the module tls records its measurements but takes no limit on them |
The check states fail_when_measurement_below or fail_when_measurement_above. A tls check takes no such limit, also not on certificate_expires_in_seconds. Use fail_when_certificate_expires_within for the time before expiry |
check_groups.mail_certificate.tls.trusted_certificate_authority_file: /etc/mmwatchdog/secrets/internal-ca.pem: contains no PEM certificates |
On the node: the file holds no certificate in PEM form, the text that starts with -----BEGIN CERTIFICATE----- |
check_groups.mail_certificate.tls.trusted_certificate_authority_file: open /etc/mmwatchdog/secrets/internal-ca.pem: no such file or directory |
On the node: /etc/mmwatchdog/secrets/internal-ca.pem is missing, or MMWatchdog cannot read /etc/mmwatchdog/secrets/internal-ca.pem |
Tested on
- Go tests:
TestTLSCAFileininternal/checksandalerts(a certificate that onlytrusted_certificate_authority_filemakes valid, the system's certificate authorities, and a file that is missing) andTestRuntimeCredentialValidationininternal/daemon(the certificate authority file atmmwatchdog validate). They ran on macOS ARM64 and, as the native suite, on the AMD64 guest of every target distribution. - The acceptance suite (
tests/integration/acceptance.py), on every target distribution: two checks of a test server whose certificate is valid for one day and trusted only throughtrusted_certificate_authority_file; withfail_when_certificate_expires_within: 1hthe check is healthy, and with48hit fails.
Why it works this way
-
The certificate warning time is required. Certbot commonly renews with 30 days left, while other certificates have shorter lifetimes. State
fail_when_certificate_expires_withinfor the certificate being checked. -
Verification is never skipped.
trusted_certificate_authority_filecovers a server with a private certificate authority without teaching an insecure habit. -
The check fails before expiry at the stated warning time. An expired certificate is an outage; the warning leaves time to renew it.
-
An unreadable
trusted_certificate_authority_filemakes the run unknown, not failed. MMWatchdog learned nothing about the server certificate being checked.
This page is docs/reference/modules/tls.md in the MMWatchdog repository.