[GH-ISSUE #389] Clarify domain and nsname in the documentation and the example config.cfg #220

New issue

Open

opened 2026-03-13 16:11:27 +03:00 by kerem · 2 comments

kerem commented

2026-03-13 16:11:27 +03:00

Owner

Originally created by @numo68 on GitHub (Jul 26, 2025).
Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/389

Not a bug, just an idea. Perhaps it is just me but I find the documentation a bit confusing. It is not readily clear what the exact meaning of

# domain name to serve the requests off of
domain = "auth.example.org"
# zone name server
nsname = "auth.example.org"

is and it takes some trial and error to find out. Perhaps rewriting the example in a way that e.g. acme.example.org serves challenges for *.intranet.example.org would make it more clear.

Thanks

Originally created by @numo68 on GitHub (Jul 26, 2025). Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/389 Not a bug, just an idea. Perhaps it is just me but I find the documentation a bit confusing. It is not readily clear what the exact meaning of ``` # domain name to serve the requests off of domain = "auth.example.org" # zone name server nsname = "auth.example.org" ``` is and it takes some trial and error to find out. Perhaps rewriting the example in a way that e.g. `acme.example.org` serves challenges for `*.intranet.example.org` would make it more clear. Thanks

kerem commented

2026-03-13 16:11:33 +03:00

Author

Owner

@numo68 commented on GitHub (Jul 27, 2025):

To clarify, what I wanted to do is the acme-dns to issue a wildcard certificate, which is valid for a subdomain that is not accessible publicly. Meaning that I have actually three things

a cloudflare-hosted example.org
a privately hosted publicly accessible auth.example.org
an intranet.example.org domain I need a wildcard certificate for (the public nameserver only serves _acme-challenge for it)

So now I have

domain = "auth.example.org"
nsname = "auth.example.org"
nsadmin = "admin.example.org"
records = [
    "auth.axample.org. A ...",
    "intranet.example.org. NS auth.example.org.",
    "_acme-challenge.intranet.example.org. CNAME {{ acmedns_subdomain }}.auth.example.org.",
]

and the example.org has NS for both auth and lan pointing to the acme-dns; it works, but I am not sure that's the intended usage.

What exactly does the acme-dns use the nsname for, I guess for the SOA record for the domain, anything else?

Thanks

@numo68 commented on GitHub (Jul 27, 2025): To clarify, what I wanted to do is the acme-dns to issue a wildcard certificate, which is valid for a subdomain that is not accessible publicly. Meaning that I have actually three things - a cloudflare-hosted `example.org` - a privately hosted publicly accessible `auth.example.org` - an `intranet.example.org` domain I need a wildcard certificate for (the public nameserver only serves `_acme-challenge` for it) So now I have ``` domain = "auth.example.org" nsname = "auth.example.org" nsadmin = "admin.example.org" records = [ "auth.axample.org. A ...", "intranet.example.org. NS auth.example.org.", "_acme-challenge.intranet.example.org. CNAME {{ acmedns_subdomain }}.auth.example.org.", ] ``` and the `example.org` has NS for both `auth` and `lan` pointing to the `acme-dns`; it works, but I am not sure that's the intended usage. What exactly does the `acme-dns` use the `nsname` for, I guess for the `SOA` record for the `domain`, anything else? Thanks

kerem commented

2026-03-13 16:11:38 +03:00

Author

Owner

@leggewie commented on GitHub (Feb 5, 2026):

I have been pulling my hair out over the exact same question.

My current understanding is that nsname is the name of the public DNS server server where acme-dns is running. This could be https://auth.acme-dns.io for example., this domain does not need like be under your control, but could be a third-party you trust. domain is the zone from your own domain for which you want to issue certificates. The confusion comes about because in the example configuration both variables are set to the same string. This works but is not necessary.

@leggewie commented on GitHub (Feb 5, 2026): I have been pulling my hair out over the exact same question. My current understanding is that nsname is the name of the public DNS server server where acme-dns is running. This could be https://auth.acme-dns.io for example., this domain does not need like be under your control, but could be a third-party you trust. domain is the zone from your own domain for which you want to issue certificates. The confusion comes about because in the example configuration both variables are set to the same string. This works but is not necessary.