Skip to main content
Video tutorial · 2:40

Manual DNS challenge

When CertAutoPilot cannot (or should not) automate your DNS provider — unsupported registrar, isolated network, change- management policy — use the manual DNS path. The backend computes the TXT record and shows it in the UI; you add it on your DNS side; you click Validate; the backend checks propagation and completes the ACME order.

When to use​

  • Your DNS provider is not one of the 19 supported providers and has no API at all.
  • Your change-management policy forbids automation writing to production DNS.
  • The zone is split-horizon or managed by a team that controls its own tooling.
  • You're issuing a one-off certificate with no intention to auto-renew.
Auto-renewal won't work

A manually-validated cert cannot auto-renew — the renewal workflow would need to publish a fresh TXT record 30 days from now, and there's nobody there to do it. Manual DNS is one-shot: Renew is rejected outright for these certificates (manual DNS certificates cannot be auto-renewed; re-issue instead), and auto-renew cannot be switched back on later. To refresh one, use Reissue and complete the manual TXT flow again — worth knowing before you reach for Renew near expiry. While the re-issue waits for the new TXT records the certificate shows awaiting_validation, but the certificate you already have keeps working and can still be downloaded and deployed, and its expiry warnings keep coming; if the validation fails, it stays in place and the certificate returns to active with the reason under Last Error. Cancel re-issue on the DNS Challenges card abandons the pending records the same way. A re-issue whose TXT records are never validated is closed by the scheduler two hours after it started (the certificate returns to its previous status and a Certificate Issuance Failed notification is sent) — validate within that window, or re-issue again for fresh records.

Issue with manual DNS​

  1. Certificates → New.

  2. Configure issuer + subject + key type as usual.

  3. At the Validation step, toggle Manual DNS. Auto-renew turns off automatically. Paste the names one per line, or separated by commas or spaces; the form groups them by the zone they fall in so you can see where each record will go. A zone is not sent with a manual DNS request — the API refuses zone_id and domain_zones for it.

  4. Submit. The backend opens an ACME order, receives the challenge tokens, and pauses — the certificate moves to status awaiting_validation.

  5. Open the certificate's detail page. The Manual DNS challenge panel lists one TXT record per identifier:

    Record name: _acme-challenge.api.example.com
    Record type: TXT
    Record value: "LoqXcYV8...WxKz" (copied exactly as shown)
    TTL: 60 seconds recommended

    The names can be in any zones — manual DNS needs no zone in CertAutoPilot. The panel shows the CertAutoPilot zone each record falls in (a dash when none of your zones covers it) and lists the records zone by zone. Copy all copies every record as a zone-file line (<name>. 60 IN TXT "<value>") and Download CSV saves them as zone,domain,record_name,type,value (every value is written exactly as the record needs it; a spreadsheet may show a value starting with - as a formula error, so import the file as text or use Copy all, which also works on a plain-HTTP page) — handy when the records go to several DNS teams. A name and its wildcard (example.com and *.example.com) share one record name with two different values: publish both values.

  6. Publish each record on your DNS side.

  7. Verify propagation (recommended):

    dig +short TXT _acme-challenge.api.example.com @1.1.1.1
  8. Click Validate on the detail page. First the backend checks that every TXT record is visible via the configured DNS resolvers (the pre-check). If any is missing, nothing is sent to the CA and the message names the missing records (up to ten, then a count): the CA validates every name of the order at once, and one missing record would fail the whole order and count against the CA's failed-validation limit. Check DNS shows each record's state (a name and its wildcard are shown separately, each with its own value). When none of the DNS servers gives an answer — the server running CertAutoPilot cannot reach them on port 53, or they answer with a server failure (a broken zone, DNSSEC for example) — the record shows No answer and Validate says so instead of asking you to create the records. When all are visible, a validate_manual_dns job asks the CA to verify and waits for every authorization to go valid.

  9. On success the cert is issued. The job waits up to 3 minutes for the CA; past that it fails with authorization(s) not valid before timeout: <domains>. Fix the record and click Validate again — the ACME order stays usable.

Propagation tips​

  • Checking too early can delay you. Public resolvers that were asked for a record before it existed remember "no such record" for the zone's negative TTL (the last value of its SOA — often 5 minutes to an hour), and they answer from many servers, so Check DNS can show a record while Validate still finds it missing. Wait a few minutes and try Validate again.

  • Keep the TTL low (60 s) on the challenge record so your change reaches the CA quickly.

  • If your DNS has a long negative-caching TTL, resolvers may cache "no TXT record exists" from before your add. Wait at least that long.

  • Check multiple public resolvers: Cloudflare (1.1.1.1), Google (8.8.8.8), Quad9 (9.9.9.9) — the CA picks one of several.

Cleanup​

After issuance succeeds, the challenge records serve no purpose. You can delete them from the DNS side. The backend does not issue cleanup calls for manual DNS (it couldn't — no API credential) — deletion is on you. Leaving them in place causes no harm.

Multi-identifier certs​

A certificate with five SANs needs five TXT records (one per identifier). Wildcard identifiers (*.example.com) contribute a single TXT at _acme-challenge.example.com — validated against the apex. If a cert mixes example.com and *.example.com, the CA requires two separate TXT values at the same record name (use a multi-value TXT; most DNS providers accept an RRset with multiple strings).

Troubleshooting​

Check DNS says the record is not visible​

Propagation delay. Retry after a minute. If still absent after 5 minutes, confirm you added the record to the right zone — a domain at registrar.com may have delegated DNS elsewhere.

Check DNS shows a different value than expected​

Common cause: the record was saved with surrounding quotes stripped, or with line breaks. The UI's Copy button produces the exact value.

authorization(s) not valid before timeout​

The CA did not mark every authorization valid within the 3-minute wait — usually because the TXT record was not yet visible to the CA's resolvers when you clicked Validate. Confirm with Check DNS, then click Validate again; the ACME order stays valid for hours after a failed validation, so restarting usually works.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Manual DNS Validation (DNS-01 Without Provider Access)YouTube ↗