Add a domain
A managed domain is a base name — home.example.com — under which local-cert is allowed to issue. It relies on a hosted zone of a provider. The wizard on the Domains page does everything in three screens.
Before you start
- A registered provider whose test is green.
- A public zone at that host, authoritative for the name. Let's Encrypt must be able to read the validation record from the Internet: a private zone won't do, even if your hosts themselves stay private.
1. Choose the provider
+ Add a domain, then select the provider. local-cert queries the account and shows the number of visible zones.
2. Choose the zone
The account's zones are listed with their identifier. A private zone is greyed out. If a zone already carries a managed domain, it is indicated.
- Base name: the zone name by default. You can narrow it to a subdomain (
lab.home.example.comin thehome.example.comzone): only names below it can receive a certificate. - Default TTL: lifetime of the records local-cert publishes. 60 seconds is fine.
3. Grant permissions, test, add
local-cert immediately tests its permissions on the zone. If they are already in place, you only need to confirm. Otherwise the screen shows what to do:
- In the AWS console, open the role (or user) shown → Permissions tab.
- Click the existing policy,
local-cert-route53— the one created with the provider — then Edit → JSON tab. Don't add a second policy: this is the one that gets extended. - Replace the whole content with the document shown, then Next → Save changes. It contains the zones already declared on this provider plus the new one: nothing is removed.
- Go back to the wizard and click Retest.
- When all the required lines show
OK, click Add the domain.
Add without waiting: the pending status
A host can take a few minutes to apply a permission change. Rather than retesting by hand, add the domain while the test is still failing (Add as pending button):
- the domain is pending: local-cert reruns the test every minute, five times, and sets it to active as soon as it succeeds;
- after five failures it goes to error, with the last refusal displayed. Fix the permissions, then click Retry check: a new cycle starts;
- until it is active, the domain receives no certificate and no record: the API answers
409and the ACME server answersrejectedIdentifier.
What the test checks
| Call | Required | Used for |
|---|---|---|
ListResourceRecordSets | yes | reading the zone, and checking that it covers the base name |
GetHostedZone | yes | finding the name servers to query during validation |
GetChange | yes | waiting for a write to propagate |
ChangeResourceRecordSets (TXT) | yes | writing the validation record |
ChangeResourceRecordSets (A) | no | publishing a host's address, if you ask for it at issuance |
Write permission is probed by deleting a record that doesn't exist: AWS checks the authorization before noticing there is nothing to delete. The test never modifies the zone.
If the test stays red
- Wait a few seconds and retest: IAM doesn't propagate instantly.
- Check that the policy was pasted on the identity shown, and not on the user when the provider goes through a role.
- If every line fails with the same message, the problem is the provider itself: use the Test button in Providers.
- If a
CAArecord exists on the zone, it must allowletsencrypt.org— the test doesn't check it, but issuance will fail.
Add anyway saves a domain whose test fails. Useful for preparing a configuration; no issuance will succeed while permissions are missing.
Next
- Give access to the domain in Keys & access: an API key with its permissions, or an EAB credential for an ACME client.
- Issue a first certificate: Quick start.
Remove a domain
Remove is refused as long as certificates exist. Force revokes them, cleans the zone as far as possible, then deletes everything. Afterwards, remember to regenerate the provider's policy (policy button) and paste it into AWS again: the removed zone no longer appears in it.