> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure TLS certificate probes

> Connect to a TLS endpoint and report days until certificate expiry.

TLS certificate probes connect to a host on a TLS port, read the
peer certificate, and report `days_until_expiry`. Use them to fire
a clear signal before a public certificate lapses.

## Configuration shape

```json theme={null}
{
  "host": "api.example.com",
  "port": 443,
  "warn_days": 30,
  "critical_days": 7
}
```

## Field reference

| Field | Default | Notes |
| - | - | - |
| `host` | required | Hostname (preferred) or IP. SNI is set automatically when the host is a hostname. |
| `port` | `443` | TLS port to connect to. |
| `warn_days` | `30` | Informational marker. The agent reports the value regardless; thresholds drive status. |
| `critical_days` | `7` | Same as above. The relationship `warn_days >= critical_days` is enforced. |

The probe accepts certificates that fail validation (expired,
self-signed, hostname mismatch). The intent is to surface the
problem rather than refuse the connection. Status is computed
from `days_until_expiry`.

## Threshold examples

| Goal | Healthy | Unhealthy |
| - | - | - |
| Standard renewal cadence | `over 30` | `under 7` |
| Aggressive (Let's Encrypt 90d) | `over 14` | `under 3` |

An expired certificate reports `0`. Set unhealthy at `under 1`.

## Reason codes

The full catalog, with the hint the console shows for each code, is in [Reason codes](https://docs.use.observer/agent/reference/reason-codes.md).

| Reason | Meaning |
| - | - |
| `no_cert` | Server completed TLS but did not present a certificate. |
| `bad_cert_date` | Certificate's `valid_to` could not be parsed. |
| `ETIMEDOUT` | Connection did not complete in time. |
| `ECONNREFUSED` | Connection refused at the TCP layer. |
| `ENOTFOUND` / `EAI_AGAIN` | The hostname did not resolve. |
| `tls_handshake_failed` | The handshake failed before a certificate was read, for example on a port that does not speak TLS. |
| `tls_error` | Other TLS-handshake error. |

> [!NOTE]
>
> **IP literals**
>
> When `host` is an IP literal, the SNI hint is omitted (RFC 6066
> forbids IPs as SNI values). Some virtual-hosted servers will not
> return the expected certificate without SNI. Probe a hostname
> whenever the system supports one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.