Skip to content
local-cert
Browse the documentation

Operations

How an issuance runs through DNS, how to choose between one certificate per host and a wildcard, how to delete and recover when a zone is no longer reachable, and the known limits.

How DNS-01 works

  1. The ACME order is created and the challenge token retrieved.
  2. UPSERT of the _acme-challenge.<fqdn> TXT record in Route53, TTL 60.
  3. Wait for INSYNC on the Route53 ChangeId.
  4. Then query the zone's authoritative name servers directly until all of them see the TXT. Not 8.8.8.8: a recursive resolver caches negative answers and will lie for the whole TTL.
  5. Notify the ACME server, validation, CSR finalization, download.
  6. Delete the TXT — including on failure (finally). An orphan _acme-challenge breaks the next attempt.

Automatic renewal triggers at not_after - renew_before_days, with a deterministic jitter of ±24 h per certificate so that a whole fleet doesn't hit Let's Encrypt at the same hour.

Two possible strategies

A — one cert per hostB — one wildcard
Public A record pointing to the private IPyesno
Certificates1 per subdomainshared *.home.example.com
LE rate limitreached quickly beyond ~40 hostsa single order
Internal topology exposed in public DNSyesno
Revocationper hostall or nothing

A is simpler and more granular. Switch to B beyond a few hosts, or if publishing your private IPs in a public zone bothers you. Both are supported: tick Wildcard in the console.

Deletion and recovery

The case that matters: the Route53 zone is no longer reachable (role revoked, zone deleted, expired credentials) and you still need to be able to clean up the database.

Nothing blocks on an external API error. Deleting a certificate revokes it with the CA on a best-effort basis and cleans up the zone on a best-effort basis: if either fails, the row is deleted anyway and whatever remains published is returned in warnings.

shell
curl -X DELETE "https://certs.example.com/api/v1/certificates/$ID?purge=true" \
  -H "Authorization: Bearer $TOKEN"
response
{
  "id": "cert_…",
  "status": "deleted",
  "warnings": [
    "Could not remove A nas.home.example.com -> 192.168.1.50 from Route53: No hosted zone found with ID: ZINACCESSIBLE. The record is still published — delete it by hand."
  ]
}

A domain cannot go away while a certificate references it. certificates.domain_id is ON DELETE RESTRICT: any remaining row pins the domain — revoked, failed or expired, not just active ones. The refusal is explicit and counted:

409
{
  "type": "conflict",
  "title": "Domain still has 3 certificate(s) (1 active). Delete them first, or repeat with ?force=true to remove them along with the domain.",
  "detail": { "certificates": 3, "active": 1, "by_status": { "issued": 1, "failed": 1, "expired": 1 } }
}

?force=true performs the cascade explicitly: best-effort CA revocation, best-effort zone cleanup, then deletion of the certificates and the domain in a single transaction. certificate_events and grants follow through SQL cascade.

shell
curl -X DELETE "https://certs.example.com/api/admin/domains/$ID?force=true" -b cookies.txt

In the console, remove shows the count when refused and replaces the button with force (N). Records left in place in the zone are listed as a warning afterwards.

ACME server: good to know

The full description of the ACME endpoint is in ACME server. The operational points:

  • The client signs the exact URL it calls. Behind a reverse proxy, either the proxy forwards X-Forwarded-Proto / X-Forwarded-Host, or you set PUBLIC_URL. A JWS "url" is … but this endpoint is … error comes from there.
  • DNS validation takes one to three minutes; the client waits on its challenge during that time.
  • These certificates appear in the console (key_type: external) with no private key and no automatic renewal: the key stays with the client, which renews on its own. POST …/renew refuses them.
  • ACME revocation (revoke-cert): an account can revoke the certificates it obtained itself.
  • Not implemented: keyChange (account key rollover) and revocation signed with the certificate's key.

Known limits

  • All SANs in a single order must belong to a single managed zone.
  • No Let's Encrypt rate-limit counter in the application: a large fleet can be refused by the CA. Worth adding if you go beyond ~40 certificates per week per registered domain.
  • The PKCS#12 export format is not implemented (JSON and PEM only).
  • Provenance markers double the number of records created in the zone (one TXT per name). That is the price of queryable ownership, given there are no tags on record sets; TAG_RECORDS=0 if you prefer a clean zone.
  • No MASTER_KEY rotation: changing it makes already-stored private keys unreadable. A renewal regenerates them.
  • A single administrator account, created at setup. No multi-user management and no password change from the console — rotation goes through scripts/reset-admin.ts.