Limited DNS server for automating DNS challenges


Acme-dns is a DNS server with a RESTful HTTP api for DNS challenge automation. You can find the project @

It also provides additional security, as the API keys that have to be stored on the server requesting the certificates are limited to only updating the TXT record. This effectively means that if the box gets compromised, the attacker gains access only to the TXT record, compared to other DNS servers providing an API, where the keys pretty much always give full control of a zone.

You are able to use it for DNS challenge automation with your existing DNS server if it just supports CNAME records (all of them do).

How it works

  • Get a generated username - api key pair, and unique subdomain with a POST request to the API
  • Create a CNAME record from your original zone, using the ACME magic subdomain “_acme-challenge.yourdomain.tld” pointing to the unique subdomain allocated to your user-key pair.
  • Automate it using your ACME client of choice. Note that the client needs to support DNS challenges, and scripting. This will be possible with the upcoming release 0.10 of Certbot as well.
  • The CA will follow the CNAME record, and request the challenge token from acme-dns subdomain.

Setting up your own instance of acme-dns

  • Get the source code from
  • Build it, and modify the config.cfg
  • Delegate a subdomain for the acme-dns to work with. This means creating two DNS records. I’m using “auth.yourdomain.tld” with an IPv4 address “” as an example for the api endpoint.
      • Create a A record for it: ns.auth.yourdomain.tld pointing to ip
      • Create a NS record for it: auth.yourdomain.tld pointing to ns.auth.yourdomain.tld
      • After the records are in place, all DNS queries with path auth.yourdomain.tld in it will be delegated to the IP address you provided
  • Run acme-dns with elevated privileges (you can run it unprivileged user too, but then you’ll have to do port forwarding rules for port 53 to be able to answer DNS queries)


  • Limited DNS server with RESTful API
  • Ability to get and use Let’s Encrypt certificate for the REST API automatically
  • Supports custom records, if you need additional records for subdomains under auth.yourdomain.tld
  • Limit TXT record update requests to predefined address range(s) using CIDR notation
  • Instant updates, so no need to sleep() in scripts while waiting for DNS propagation.
  • SQLite / PostgreSQL as a backend.

If you want to test it out, I’m running an instance @

All kind of feedback is welcome and appreciated, be it critique or feature request!


took a minute for me to figure out the benefits of this but now I get it

maybe a diagram and an explanation that only the Name server for the sub-domain is updated (not for the entire TLD).

I can see a lot of use for MSP, Service Providers and SaaS providers for this.


Yeah, I probably should draw something up, thanks for the suggestion! Few detailed use cases was something that I was asked to write down too.


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