TLS monitors

Checking a TLS handshake and the remaining lifetime of the certificate it presents.

Purpose

A TLS monitor checks that a TLS handshake completes against a host and port, that the certificate chain presented is trusted, and that the certificate's remaining lifetime is above a configured threshold. It is the monitor type for tracking certificate expiry, rather than a byproduct of checking an https:// URL.

Use cases

Tracking certificate expiry for a service whose certificate is renewed on its own schedule, independent of whatever HTTP monitor also checks the service.
A TLS-terminating endpoint that is not HTTP at all — a mail server, a database with TLS enabled, or any other TLS service on its own port.

Configuration

Required:

Target — a bare host, under the same rules as a TCP monitor's target: never a URL, never a host:port pair.
Interval and timeout — see Concepts: states.

Optional:

Port — defaults to 443 if not stated.
Expiry threshold — the remaining certificate lifetime, in days, below which the check reports DOWN. Defaults to 14 days if not stated. Zero is refused rather than treated as "no threshold": a threshold of zero would mean "tell me once it has already expired," which is the one outcome certificate-expiry monitoring exists to prevent. The threshold may be set up to 365 days; a longer threshold would hold the monitor DOWN for most of an ordinary certificate's life, which stops being an early warning and becomes noise.

Defaults

Field	Default
Port	443
Expiry threshold	14 days

Validation

The target follows the same host-target rules a TCP monitor's does. The port must be between 1 and 65535. The expiry threshold, if stated, must be between 1 and 365 days.

Probe behavior

The probe connects to the target and port and completes a TLS handshake, validating the certificate chain. If the handshake succeeds and the chain verifies, it compares the certificate's remaining lifetime against the configured expiry threshold.

Success

The check is UP when the handshake completes, the certificate chain verifies, and the remaining lifetime is at or above the expiry threshold.

Failure

A failed TLS check states one of these causes:

Cause	Meaning
`invalid_target`	The probe could not even form a connection attempt from the configuration — an invalid host, an invalid port, or an invalid expiry threshold.
`dns`	The target did not resolve.
`tcp_timeout`	The connection attempt neither completed nor was refused within the monitor's timeout.
`tls_handshake_failed`	The connection failed before a handshake could be attempted for any other reason (refused, unreachable, or otherwise), or the handshake itself did not complete for a reason that is not a trust decision — the peer spoke no TLS, closed the connection, or refused every offered parameter.
`tls_untrusted`	The certificate chain did not verify: unknown authority, wrong host name, or a chain that does not build.
`cert_expired`	The certificate's `notAfter` has already passed.
`cert_expiring`	The certificate verified, but its remaining lifetime is below the configured threshold.

cert_expiring is a DOWN cause, not a separate warning state — TLS checks are binary UP or DOWN, the same as every other monitor type, and this product has no third state to put an early-warning result in. A TLS monitor approaching its expiry threshold is DOWN in exactly the sense that draws attention to it.

Evidence

A check result records the cause if it failed, and, when a handshake completed, the certificate's expiry timestamp — which is what a history row or an incident can show alongside a cert_expiring or cert_expired cause, rather than only the cause string.

Latency interpretation

Latency is the time to complete the TCP connection and the TLS handshake together — it will generally be higher than a TCP monitor's latency against the same host and port, because it includes the handshake's own round trips.

Consensus interaction

A TLS monitor's states, and how its assigned nodes' observations become one published state, follow the same rules every monitor type does — see Concepts: consensus.

Common mistakes

Setting the expiry threshold to a large number of days "to be safe" — a threshold near or above the certificate's own validity period holds the monitor DOWN for most of its life, which is a check nobody can act on.
Expecting an HTTP monitor against an https:// target to also track certificate expiry — it does not; an HTTP monitor's network cause folds a TLS handshake or trust problem in with every other transport failure at check time, and there is no HTTP-monitor equivalent of cert_expiring. Use a TLS monitor for that.

Troubleshooting

Result is cert_expiring and you expected more notice — raise the expiry threshold, up to 365 days, rather than treating the result as wrong; the threshold is exactly the notice window you asked for. - Result is tls_untrusted for a certificate you believe is valid — confirm the chain verifies against the trust store the probing node runs under, and that the target host name matches what the certificate covers.

Security and network considerations

The probe runs from the nodes assigned to the monitor and validates the certificate chain the same way any TLS client at that node's location would. A certificate that is valid from one network but not another — an internal CA trusted only on some nodes, for example — will report tls_untrusted from the nodes that do not trust it, which is the monitor correctly reporting what those nodes can verify, not a false alarm.

Example

target: mail.example.com
port: 443
expiry_threshold_days: 14
interval_seconds: 300
timeout_seconds: 10

TCP monitors — for checking the port without validating TLS.
HTTP monitors — for checking an https:// URL's response, rather than its certificate's remaining lifetime.
Concepts: states

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.