Pingtower
Docs
domainexpiry
Read a registered domain's expiry date from its registry, over RDAP or WHOIS, and warn 30 days before it lapses.
A lapsed domain takes every service under it down at once, and the registry publishes the date months ahead. This check reads that date from the registry, never from the domain’s own servers. It reports the days left on every run, is degraded inside warn_before, and is down once the domain has expired.
It runs on Pingtower’s servers as a hosted check and on your own agents. The answer is the same from everywhere, and registries rate-limit by address, so a check runs from one place only. Name one source, or none and Pingtower picks one. When Pingtower runs it, its interval defaults to once a day and its timeout to 30 seconds. See Domain expiry runs from one place.
Parameters
| Parameter | Default | Meaning |
|---|---|---|
domainREQUIRED | The domain to watch, such as example.com. | |
warn_before | 720h (30 days) | Time left at which the check is degraded. |
The check watches the registered domain, the name one level below its public suffix: www.example.com is watched as example.com, and example.co.uk stays itself. A name under a privately run suffix is watched as the registered domain above it, so acme.github.io is watched as github.io. Write an internationalised name in its xn-- form. An IP address or a bare public suffix is refused.
How it finds the date
- IANA’s RDAP bootstrap names the RDAP service for the domain’s top-level domain. The agent fetches it once a day.
- The registry’s RDAP record gives the expiration date. When the record links the registrar’s own RDAP record, that is read too, and the earlier date is reported. A gTLD registry renews automatically at expiry, so its date can run a year ahead of what the registrant has paid for.
- A top-level domain with no RDAP service is read over WHOIS, for the registries whose expiry line the check knows:
.io,.meand.se.
Status
| Result | Status |
|---|---|
More than warn_before left | up: domain registered for 241d (2027-05-31) |
warn_before or less left | degraded: domain expires in 12d (2026-10-14) |
| Expired | down: domain expired 3d ago (2026-09-29) |
| The registry holds no such domain | down: example.com is not registered |
What the check can’t learn is never reported as down. When the registry publishes no expiry date, or the top-level domain has neither RDAP nor a WHOIS format the check reads, the run is a check error tagged status:error with the key reason set to no_expiry_published. When the registry can’t be reached, reason is registry_unreachable. Neither votes toward an alert.
Measurements
| Key | Meaning |
|---|---|
days_until_expiry | Days left, negative once expired |
lookup_ms | The whole lookup |
source | Label: rdap or whois |
expiry_from | Label: registry or registrar, whose date was reported |
The check needs addons agent 0.4.0 or later; an older agent reports it as an unknown addon.
Example
- id: acme-domain
addon: domainexpiry
interval: 24h
timeout: 30s
with:
domain: acme.example
warn_before: 1440h # 60 days
A rule for it
{"name":"domain-expiring","match":{"tags":["addon:domainexpiry"]},
"conditions":[{"key":"days_until_expiry","op":"lte","value":14}],
"identifier_keys":["check"],"renotify_minutes":1440}