[GH-ISSUE #255] CNAME Record confusion

kerem commented

2026-03-13 15:51:39 +03:00

Owner

Originally created by @gpz1100 on GitHub (Feb 12, 2021).
Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/255

I've read the readme as well as several tutorials on implementation.

What i'm still not entirely clear on is why one needs a permanent (or for as long as you want it to keep renewing) CNAME record _acme-challenge.subdomain.domain.tld record in the first place in the dns zone.

Since the request for lookup of such record ultimately gets passed down to the acme-dns service (running locally on your machine), which has already associated the _acme-challege.subdomain.domain.tld to a distinct username/password hash in addition to a subdomain hash (fc31d598-4138-49b3-bb26-505dd17dab88.acme.domain.tld. It can query its database to resolve which domain the request is applicable to and update the txt then respond accordingly to certbot.

Originally created by @gpz1100 on GitHub (Feb 12, 2021). Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/255 I've read the readme as well as several tutorials on implementation. What i'm still not entirely clear on is why one needs a permanent (or for as long as you want it to keep renewing) CNAME record `_acme-challenge.subdomain.domain.tld` record in the first place in the dns zone. Since the request for lookup of such record ultimately gets passed down to the acme-dns service (running locally on your machine), which has already associated the `_acme-challege.subdomain.domain.tld` to a distinct username/password hash in addition to a subdomain hash `(fc31d598-4138-49b3-bb26-505dd17dab88.acme.domain.tld`. It can query its database to resolve which domain the request is applicable to and update the txt then respond accordingly to certbot.

kerem commented

2026-03-13 15:51:44 +03:00

Author

Owner

@webprofusion-chrisc commented on GitHub (Feb 12, 2021):

Yeah but not everyone runs their own acme-dns service, so not everyone is delegating their zone. Having a CNAME just serves as a standard way to present something to the CA that they can then follow to the correct record. It works really well.

@webprofusion-chrisc commented on GitHub (Feb 12, 2021): Yeah but not everyone runs their own acme-dns service, so not everyone is delegating their zone. Having a CNAME just serves as a standard way to present something to the CA that they can then follow to the correct record. It works really well.

kerem commented

2026-03-13 15:51:49 +03:00

Author

Owner

@gpz1100 commented on GitHub (Feb 12, 2021):

This isn't clicking... Doesn't acme-dns require one actually run the service [somewhere]?

I'm trying to understand why the entire _acme-challenge.subdomain.domain.tld can't be hidden/obfuscated entirely.

@gpz1100 commented on GitHub (Feb 12, 2021): This isn't clicking... Doesn't acme-dns require one actually run the service [somewhere]? I'm trying to understand why the entire _acme-challenge.subdomain.domain.tld can't be hidden/obfuscated entirely.

kerem commented

2026-03-13 15:51:55 +03:00

Author

Owner

@webprofusion-chrisc commented on GitHub (Feb 12, 2021):

Yes, someone need to run the service but it can be you or someone you trust. i.e. https://auth.acme-dns.io/register is an instance of acme-dns which is hosted by the author. It answers queries for anyone the is registered and pointing their CNAME at it.

_acme-challenge. is a public record which the certificate authority will query. Everyone can see it and there is no advantage to it being hidden. It is simply proof (via a TXT record value) that when Let's Encrypt asked you to prove you control your domain/subdomain (by setting the TXT record value to a specific random value), that you then went ahead and updated the TXT record as they asked, then LE see that and so, ok, you control that domain, here's a cert.

So, ACME dns validation works by asking you to populate _acme-challenge, then the CA queries it to make sure you did as asked. Many people use other DNS providers/API to simply update their actual DNS with the TXT record, or they even do it manually (don't do that, it's error prone and manual). The problem was that there are many many (..many) different DNS APIs and each one needs a different way to communicate with it.

acme-dns was invented as a least-privilege way of updating your _acme-challenge response TXT record via a single standard API. You create the CNAME once, from then on your acme client talks to acme-dns to make sure the TXT record value is up to date for validations.

@webprofusion-chrisc commented on GitHub (Feb 12, 2021): Yes, someone need to run the service but it can be you or someone you trust. i.e. https://auth.acme-dns.io/register is an instance of acme-dns which is hosted by the author. It answers queries for anyone the is registered and pointing their CNAME at it. _acme-challenge. is a public record which the certificate authority will query. Everyone can see it and there is no advantage to it being hidden. It is simply proof (via a TXT record value) that when Let's Encrypt asked you to prove you control your domain/subdomain (by setting the TXT record value to a specific random value), that you then went ahead and updated the TXT record as they asked, then LE see that and so, ok, you control that domain, here's a cert. So, ACME dns validation works by asking you to populate _acme-challenge, then the CA queries it to make sure you did as asked. Many people use other DNS providers/API to simply update their actual DNS with the TXT record, or they even do it manually (don't do that, it's error prone and manual). The problem was that there are many many (..many) different DNS APIs and each one needs a different way to communicate with it. acme-dns was invented as a least-privilege way of updating your _acme-challenge response TXT record via a single standard API. You create the CNAME once, from then on your acme client talks to acme-dns to make sure the TXT record value is up to date for validations.

kerem commented

2026-03-13 15:52:00 +03:00

Author

Owner

@krouter commented on GitHub (Feb 13, 2021):

Yes, someone need to run the service but it can be you or someone you trust. i.e. https://auth.acme-dns.io/register is an instance of acme-dns which is hosted by the author. It answers queries for anyone the is registered and pointing their CNAME at it.

_acme-challenge. is a public record which the certificate authority will query. Everyone can see it and there is no advantage to it being hidden. It is simply proof (via a TXT record value) that when Let's Encrypt asked you to prove you control your domain/subdomain (by setting the TXT record value to a specific random value), that you then went ahead and updated the TXT record as they asked, then LE see that and so, ok, you control that domain, here's a cert.

So, ACME dns validation works by asking you to populate _acme-challenge, then the CA queries it to make sure you did as asked. Many people use other DNS providers/API to simply update their actual DNS with the TXT record, or they even do it manually (don't do that, it's error prone and manual). The problem was that there are many many (..many) different DNS APIs and each one needs a different way to communicate with it.

acme-dns was invented as a least-privilege way of updating your _acme-challenge response TXT record via a single standard API. You create the CNAME once, from then on your acme client talks to acme-dns to make sure the TXT record value is up to date for validations.

can you tell how to setup acme-dns to run as my own instance, and not point to https://auth.acme-dns.io/register ??
i've followed the installation instructions, build using go and enabled the service too.
Still not sure where and how in the config file!! do we tell acme-dns to behave as self-hosted instance?

@krouter commented on GitHub (Feb 13, 2021): > Yes, someone need to run the service but it can be you or someone you trust. i.e. https://auth.acme-dns.io/register is an instance of acme-dns which is hosted by the author. It answers queries for anyone the is registered and pointing their CNAME at it. > > _acme-challenge. is a public record which the certificate authority will query. Everyone can see it and there is no advantage to it being hidden. It is simply proof (via a TXT record value) that when Let's Encrypt asked you to prove you control your domain/subdomain (by setting the TXT record value to a specific random value), that you then went ahead and updated the TXT record as they asked, then LE see that and so, ok, you control that domain, here's a cert. > > So, ACME dns validation works by asking you to populate _acme-challenge, then the CA queries it to make sure you did as asked. Many people use other DNS providers/API to simply update their actual DNS with the TXT record, or they even do it manually (don't do that, it's error prone and manual). The problem was that there are many many (..many) different DNS APIs and each one needs a different way to communicate with it. > > acme-dns was invented as a least-privilege way of updating your _acme-challenge response TXT record via a single standard API. You create the CNAME once, from then on your acme client talks to acme-dns to make sure the TXT record value is up to date for validations. can you tell how to setup acme-dns to run as my own instance, and not point to https://auth.acme-dns.io/register ?? i've followed the installation instructions, build using go and enabled the service too. Still not sure where and how in the config file!! do we tell acme-dns to behave as self-hosted instance?

kerem commented

2026-03-13 15:52:05 +03:00

Author

Owner

@gpz1100 commented on GitHub (Feb 13, 2021):

^^I followed this guide with successful results;

https://gauravsohoni.wordpress.com/2020/07/21/renewing-letsencrypt-wildcard-ssl-certificate-with-acme-dns/

And no, you should not remove the cname record as that will break renewals.

@gpz1100 commented on GitHub (Feb 13, 2021): ^^I followed this guide with successful results; https://gauravsohoni.wordpress.com/2020/07/21/renewing-letsencrypt-wildcard-ssl-certificate-with-acme-dns/ And no, you should not remove the cname record as that will break renewals.

kerem commented

2026-03-13 15:52:10 +03:00

Author

Owner

@aduzsardi commented on GitHub (Mar 23, 2022):

just to note here , as i think it would be helpful for others as well
you don't actually need acme-dns for this to work, for example you could just use AWS's Route53 or any other DNS service where you can restrict what an API key can do, and then just create a script to update the _acme-challenge RR.
that being said , acme-dns does provide a convenient way for you to do this if you don't have access to DNS provider with an API

@aduzsardi commented on GitHub (Mar 23, 2022): just to note here , as i think it would be helpful for others as well you don't actually need acme-dns for this to work, for example you could just use AWS's Route53 or any other DNS service where you can restrict what an API key can do, and then just create a script to update the _acme-challenge RR. that being said , acme-dns does provide a convenient way for you to do this if you don't have access to DNS provider with an API

Rows
Columns

[GH-ISSUE #255] CNAME Record confusion #128