Propagation & resolver settings
Before CertAutoPilot asks the CA to validate a DNS-01 challenge, it checks that the _acme-challenge TXT record is actually visible from public DNS. This page covers what that pre-check does and the org-wide settings that control it, under Settings → General.
What the pre-check does
The pre-check is an optimisation, not the validation itself: it avoids spending a CA validation attempt (which counts against the CA's failed-validation rate limits) on a record that hasn't propagated yet. The CA is always the authoritative validator and does its own lookup.
It applies to both DNS-01 paths:
| Path | Where the check runs |
|---|---|
| Automated DNS-01 (zone + credential) | By default the phased flow runs: the worker presents the TXT records, then a self-rescheduling propagation gate polls your resolvers (no worker held between checks) until the records are visible or the propagation deadline expires, and only then asks the CA to validate. The synchronous lego pre-check path (AddRecursiveNameservers) is used when phased mode is disabled, for the sequential RRset-replacing provider RFC 2136, and for Cloudflare, DigitalOcean, OVH and Plesk — those four clean up their TXT record inside the presenting process, so they cannot use the phased flow's separate cleanup job. |
| Manual DNS (operator-created records) | Clicking Validate on the certificate first queries the resolvers for every expected TXT value. If any record is not visible, validation is not enqueued: the error names the missing records (up to ten, then a count) — the CA validates every name at once, and one missing record fails the whole order. A name and its wildcard share one record name with two values; each value is checked. |
Resolvers
Settings → General → DNS Resolvers. When the list is empty, the built-in public set is used:
8.8.8.8:53(Google)8.8.4.4:53(Google)1.1.1.1:53(Cloudflare)
The same list is also what DNS providers use to find the zone they write the _acme-challenge record into (an SOA lookup) — on issuance and renewal, on record cleanup and in the credential Test. When the list is empty, that lookup asks the public set above too; the CertAutoPilot server's own resolver (inside Kubernetes, the cluster DNS) is not used. RFC 2136 is the exception: it finds the zone by asking its own configured DNS server. If the server cannot reach public DNS, or your zones are visible only on internal resolvers, enter those resolvers here. When the zone cannot be found, the error names the resolvers that were asked.
Custom entries accept a bare IP or hostname (10.0.0.53, dns.internal) — port :53 is appended automatically — or an explicit host:port. IPv6 literals with a port must be bracketed: [2001:db8::1]:53. A malformed entry (an empty port such as 8.8.8.8:, a bracketed address without a port) is refused when the settings are saved, and the list holds at most 16 entries. The UI field takes multiple entries separated by comma or space.
If your network blocks outbound DNS to public resolvers, the default set will never see your records and every validation stalls at the pre-check. Point the list at resolvers you can actually reach — or use skip-precheck if those resolvers can't see what the CA sees.
Require-all vs allow-partial
dns_propagation_allow_partial (Allow Partial Propagation switch):
- Off (default, strict)
- Phased flow: a TXT record counts as propagated only when every configured resolver returns it.
- Synchronous flow (RFC 2136, Cloudflare, DigitalOcean, OVH, Plesk, or every provider with phased mode off): CertAutoPilot asks every authoritative nameserver of the zone directly on port 53 and waits until all of them return the record. The configured resolvers are only used to find those nameservers and to follow a CNAME on the challenge name. Every nameserver in the zone's NS set must therefore be reachable from CertAutoPilot, and zone transfers to secondaries must finish within the propagation timeout.
- On (partial) — on both flows, a single configured resolver returning the record is enough, and the authoritative nameservers are not asked. Use on networks that can reach only one (often internal) resolver, or when some listed nameservers are not reachable from CertAutoPilot.
Skip the pre-check
dns_propagation_skip_precheck (Skip Propagation Pre-check switch) bypasses the local gate entirely and lets the CA validate directly. Turn it on when the local check can't see what the CA sees:
- Split-horizon DNS — internal resolvers answer differently from the public view the CA queries.
- No outbound DNS — the CertAutoPilot host cannot query any resolver that carries the public zone.
With the gate off, a record that genuinely hasn't propagated wastes a CA validation attempt — and failed validations count against CA rate limits (Let's Encrypt: per-account, per-hostname). Keep the gate on unless it is a false blocker.
Timeout & poll interval
Two budget knobs under Settings → General → Runtime Limits shape how long DNS propagation may be waited on and how often it is re-checked:
| Setting | JSON field | Default | Allowed range |
|---|---|---|---|
| DNS Propagation Timeout | dns_propagation_timeout_seconds | 120 s | 30–600 s |
| DNS Poll Interval | dns_propagation_poll_interval_seconds | 5 s | 2–60 s (must be < timeout) |
The poll interval must be strictly less than the timeout; the API rejects the update otherwise. Each individual resolver query in the pre-check is capped at 5 s regardless of these settings.
dns_propagation_timeout_seconds and dns_propagation_poll_interval_seconds are read only on the synchronous path — manual DNS, HTTP-01, RFC 2136, and the Cloudflare, DigitalOcean, OVH and Plesk providers. On the phased flow (the default everywhere else) the wait is governed by dns_propagation_deadline_seconds instead.
Two additional settings govern the phased flow: dns_propagation_deadline_seconds — how long the propagation gate keeps polling before giving up (default 1800 s, allowed 300–14400 s; it can exceed the synchronous in-worker cap because the gate never holds a worker; an order with a Windows DNS zone waits at least 2 hours whatever the setting — Windows DNS) — and dns_propagation_phased_disabled, the kill-switch that reverts automated DNS-01 to the synchronous path (default false = phased ON).
Settings reference
All of these fields live on the org-wide general settings document (there is no per-zone or per-certificate override):
A DNS credential carries Propagation strategy and Nameserver override fields in the API and the credential form. They are stored but nothing reads them — resolver selection is org-wide only, via dns_resolvers below. Use that setting instead.
| JSON field | Type | Default |
|---|---|---|
dns_resolvers | string list | empty → public set for the propagation pre-check and the zone lookup |
dns_propagation_allow_partial | bool | false (require all) |
dns_propagation_skip_precheck | bool | false (gate on) |
dns_propagation_timeout_seconds | int | 120 |
dns_propagation_poll_interval_seconds | int | 5 |
dns_propagation_deadline_seconds | int | 1800 (300–14400; phased gate) |
dns_propagation_phased_disabled | bool | false (phased flow ON) |
Troubleshooting propagation stalls
- Certificate stuck in validating: see "Validating" forever.
- Manual DNS shows "no TXT records found via the configured DNS resolvers" (none visible) or "
of (some missing, named): those records aren't visible yet from the resolvers in your list — check withTXT records are not visible yet …" dig TXT _acme-challenge.<name> @8.8.8.8, wait out your provider's propagation delay, or enable skip-precheck on split-horizon networks. See also manual DNS propagation tips. - Only some resolvers see the record and you're on strict mode: either wait, or switch on allow-partial if the lagging resolver is expected (single reachable resolver).
API
Settings are org-wide and require the Admin role:
GET /api/v1/settings/general
PUT /api/v1/settings/general