Understanding the DNS-01 challenge and ACME DNS

Let's say I want to have certificates being created/updated for different services within my domain. I would like to have "something" that will renew certificates on its own and then handle them to either some automated deployment or let me know they are ready to be deployed for the systems that need manual intervention. Reading through Challenge Types - Let's Encrypt, it seems that is doable by using DNS-01 challenge, which requires me to update the txt records at the time I submit a request to update the certs.
It seems one of the ways to achieve that is using ACME DNS, but looking at the repo it creates a webpage?

1 Like

In terms of automation, imho makes no difference whether the cert is renewed via dns or http.
for the txt records there are plugins for many dns service providers.
there are also many example scripts for this, this script works for me https://teanet.org/downloads/certhook_rfc2136.sample.sh
I'm not sure what you mean by "repo it creates a webpage?" mean

1 Like

In order to understand acme-dns, you need to understand the dns-01 challenge by itself first.

You're correct that you (or your ACME client) will need to create TXT records when requesting a new certificate (renewals are the same as new orders). Ideally, this involves using an ACME client that knows how to create/remove TXT records from whatever software or provider hosts the public DNS zone(s) for the name(s) in your cert. You provide the client with credentials to your DNS provider's API and it takes care of the rest.

But what if your DNS provider doesn't have an API? Or what if your ACME client doesn't have a plugin for your specific DNS provider? Or what if your organization doesn't want to store the API credentials for their DNS zone on your web server?

acme-dns essentially acts as a DNS middle-man specifically for ACME challenge TXT records. It is both a minimal DNS server and an HTTP based REST API. You set it up so at least the DNS service is reachable from the Internet and authoritative for a custom zone like acme.example.org and the REST API is reachable from your ACME client.

Now instead of giving your ACME client credentials to your real DNS provider, you instead just give it the hostname of your acme-dns instance. The client registers with acme-dns to create the TXT records. The TXT records will be created using a random/unique FQDN in the acme-dns server's zone. Then acme-dns will tell your client what those FQDNs are and your client will tell you to go create CNAME records from your real domain to the random FQDNs. The CNAME creation is a one-time step for each new name you are trying to get a certificate for.

When your client asks the ACME server to validate the TXT records, it will query the CNAME records, get redirected to your acme-dns instance, which will return the valid TXT records and the order will succeed.

On a renewal, everything is the same except the client doesn't need to re-register with acme-dns. It publishes the new TXT values to the same random FQDNs it did before. And since your CNAME record still exists from before, everything succeeds without user interaction.


When acme-dns is running, it provides two services on different ports:

  1. a dns server on port 53, to answer the acme-challenge lookups
  2. a web-enabled api on port 80 or 443, used by humans/clients to register domains and challenges

There's no real "webpage" on the api. pretty much every operation by a human will generate an error message. it can be password protected, served on a higher port, or locked within your LAN. It only exists for the input/management of the challenges.

FWIW, I only run acme-dns when running a renewal or issue. I use hooks to invoke short scripts that: 1) start/stop the server; and 2) enable/flush ip-tables rules. That strategy has eliminated any concerns I had over potential future security issues on acme-dns. (The code appears to be safe, but I don't really need to worry about potential exploits since it is only active occasionally)


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.